API Docs

Update Process Management Settings

Updates the process management settings of an App.
For more information refer to the following article:
Setting Process Management (External link)

This API updates the pre-live settings.
After using this API, use the following API to deploy the settings to the live App:
Deploy App Settings

MethodPUT
URLhttps://{subdomain}.kintone.com/k/v1/preview/app/status.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/status.json
Authentication Password Authentication , API Token Authentication , Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • App Management Permissions are needed.

Request Parameters

Parameters that are ignored will not be updated.

Parameter Type Required Description
app Integer or String Yes The App ID.
enable Boolean or String The on/off settings of the process management settings.
  • true: Process management settings is enabled.
  • false: Process management settings is disabled.
states Object An object containing data of the process management statuses.
When adding or updating a status, specify the existing statuses in states as well.
If not specified, the existing statuses will be deleted.
states.{status_name} Object An object containing the settings of each status.
  • Add a new status: Specify a status name that does not exist.
  • Update a status: Specify the name of the status to be updated.
  • Delete a status: Do not specify the status name for deletion.
The first status cannot be added. To change the first status, update the name of the existing first status.
states.{status_name}.name String Conditional The status name.
The maximum length is 64 characters.
Required, if stating a new status for {status_name}. In this case, state the same value used for {status_name}.
states.{status_name}.index Integer or String Conditional The display order (ascending from 0) of the Status, when listed with the other statuses. Required, if setting the {status_name} parameter.
states.{status_name}.assignee Object An object containing data of the Assignee settings.
states.{status_name}.assignee.type String Conditional 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
Required, if setting the {status_name}.assignee parameter.
states.{status_name}.assignee.entities Array Conditional An array listing data of the Assignees.
Required, if setting the {status_name}.assignee parameter.
states.{status_name}.assignee.entities[].entity Object Conditional An object containing user data of the Assignees.
Required, if setting the entities parameter.
states.{status_name}.assignee.entities[].entity.type String Conditional The entity type of the Assignee.Required, for each entity stated.
Departments cannot be specified in guest space Apps.
states.{status_name}.assignee.entities[].entity.code String Conditional The code of the Assignee.
To specify guest space users, add the string guest/ before the guest's log in name.
If FIELD_ENTITY is specified for the entity.type, state the field code of the following fields:
  • Created by
  • Updated by
  • User selection
  • Department selection
  • Group selection
If CUSTOM_FIELD is specified for entity.type, state the field code of the Custom Field.
For more information, refer to the following article:
Adding Fields in User Information (Custom Fields) (External link)
If CREATOR is specified for entity.type, ignore this parameter.
states.{status_name}.assignee.entities[].includeSubs Boolean or String The Include affiliated departments settings of the department.
  • true: Affiliated departments are included as Assignees
  • false: Affiliated departments are not included as Assignees
If ignored, this value is false.
actions Array An array containing data of the Actions.
actions[].name String Conditional The Action name.
The maximum length is 64 characters.
Required, if setting the actions parameter.
actions[].from String Conditional The Status name before taking action.
If a Status name that you want to specify has been changed, place the changed value for this parameter.
Required, if setting the actions parameter.
actions[].to String Conditional The Status name after taking action.
If a Status name that you want to specify has been changed, place the changed value for this parameter.
Required, if setting the actions parameter.
actions[].filterCond String The branch criteria of the action, specified as a query.
For more information on query formats refer to the following document:
Query String
The Status field cannot be included in the query.
revision Integer or String Specify the revision number of the settings that will be deployed.
The request will fail if the revision number is not the latest revision.
The revision will not be checked if this parameter is ignored, or -1 is specified.

Sample Request

JavaScript using kintone.api() 

 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
67
68
69
70
71
72
73
74

var body = {
  'app': '5',
  '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': 'Created_by'
            },
            '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': ''
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/preview/app/status.json', true), 'PUT', 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
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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

var body = {
  'app': '5',
  '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': 'Created_by'
            },
            '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': ''
    }
  ],
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT and DELETE on Kintone.
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/k/v1/preview/app/status.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Response Parameters

Parameter Type Description
revision String The revision number of the App settings.

Sample Response

1
2
3

{
  "revision": "3"
}