Update Process Management Settings

Updates the process management settings of an App.
After using this API, the Deploy App Settings API API must be used for the settings to be deployed to the live App.

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 Value Required Description
app Integer or String Yes The App ID.
enable Boolean or String 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.
states.{status_name} Object An object containing the settings of each status.
Specify the status before taking action, for {status_name}.
If a status that does not exist is specified for {status_name}, it will be added as a new status. If an existing status is not specified for {status_name}, that status will be deleted.
states.{status_name}.name String Conditional The status name.
The maximum length is 64 characters.
Required, if stating a new status for states.{status_name}. In this case, state the same value used for states.{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.
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.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
  • FIELD_ENTITY: User/Group/Department selection field
  • CREATOR: Created by field
  • CUSTOM_FIELD: Custom Field (External link)
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 (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.
Check here for more data on query formats.
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 REST API Request)

 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
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
85
86
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"
}