Get Process Management Settings

Gets the process management settings of an App.

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/app/status.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/status.json
Authentication Password Authentication , API Token Authentication , Session Authentication
Content-Typeapplication/json (not needed if specifying the query with a query string)

Contents

Pre-live Settings

Apps may hold pre-live settings that have not yet been deployed to the live App.
Access the pre-live settings with the below URL.

URL https://{subdomain}.kintone.com/k/v1/preview/app/status.json
URL(guest space) https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/status.json

Permissions

  • Permission to view records or add records is needed when obtaining information of live apps.
  • App Management Permissions are needed when obtaining information of pre-live settings.

Request Parameters

Parameter Value Required Description
app Integer or String Yes The App ID.
lang String The localized language to retrieve the data in:
  • default: retrieves the default names
  • en: retrieves the localized English names
  • zh: retrieves the localized Chinese names
  • ja: retrieves the localized Japanese names
  • user: retrieves the localized names, in the same language as the language setting* set on the user used for the authentication.
If ignored, the default names will be retrieved.

*If the user language setting is set to Use Web browser settings, the settings set in the Accept-Language header will be used. If there is no Accept-Language header, the language set in the Localization settings in the System Administrator's menu will be used.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var body = {
  'app': 1
};

kintone.api(kintone.api.url('/k/v1/app/status.json', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
var url = 'https://{subdomain}.kintone.com/k/v1/app/status.json?app=1';
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send();

Response Parameters

Parameter Type Description
enable Boolean The on/off settings of the process management settings.
  • true: The process management settings is enabled.
  • false: The process management settings is disabled.
states Object An object containing data of the process management statuses.
null is returned for Apps that have never enabled the process management settings before.
states.{status_name}.name String The status name.
states.{status_name}.index String The display order (ascending) of the Status, when listed with the other statuses.
states.{status_name}.assignee Object An object containing data of the Assignee settings.
states.{status_name}.assignee.type String The Assignee List type of the Status.
  • ONE: User chooses one assignee from the list to take action
  • ALL: All assignees in the list must take action
  • ANY: One assignee in the list must take action<
The status with the lowest index will always return ONE.
states.{status_name}.assignee.entities Array An array listing data of the Assignees. They are listed in the same order as in the GUI.
states.{status_name}.assignee.entities[].entity Object An object containing user data of the Assignees.
Inactive users, deleted users/departments/groups and deleted custom fields will not be included in the response. For more information on custom fields, refer to the following article:
Adding Fields in User Information (Custom Fields) (External link)
states.{status_name}.assignee.entities[].entity.type String The entity type of the Assignee.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
  • FIELD_ENTITY: User/Group/Department selection field
    CREATOR: Created by field
    CUSTOM_FIELD: Custom Fields
states.{status_name}.assignee.entities[].entity.code String
The code of the Assignee.
The following entities will return the following values:To specify guest space users, add the string such as, guest/ before the guest's log in name.
states.{status_name}.assignee.entities[].includeSubs Boolean The Include affiliated departments settings of the department.
  • true: Affiliated departments are included as Assignees
  • false: Affiliated departments are not included as Assignees
actions Array An array containing data of the Actions. They are listed in the same order as in the GUI.
null is returned for Apps that have never enabled the process management settings before.
actions[].name String The Action name.
actions[].from String The status before taking action.
actions[].to String The status after taking action.
actions[].filterCond String The branch criteria of the action.
For more data on query formats refer to the following document:
Query String
revision String The revision number of the App settings.

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "enable": true,
  "states": {
    "Not started": {
      "name": "Not started",
      "index": "0",
      "assignee": {
        "type": "ONE",
        "entities": []
      }
    },
    "In progress": {
      "name": "In progress",
      "index": "1",
      "assignee": {
        "type": "ALL",
        "entities": [
          {
            "entity": {
              "type": "USER",
              "code": "user1"
            },
            "includeSubs": false
          },
          {
            "entity": {
              "type": "FIELD_ENTITY",
              "code": "creator"
            },
            "includeSubs": false
          },
          {
            "entity": {
              "type": "CUSTOM_FIELD",
              "code": "Boss"
            },
            "includeSubs": false
          }
        ]
      }
    },
    "Completed": {
      "name": "Completed",
      "index": "2",
      "assignee": {
        "type": "ONE",
        "entities": []
      }
    }
  },
  "actions": [
    {
      "name": "Start",
      "from": "Not started",
      "to": "In progress",
      "filterCond": "Record_number = \"1\""
    },
    {
      "name": "Complete",
      "from": "In progress",
      "to": "Completed",
      "filterCond": ""
    }
  ],
  "revision": "3"
}