API Reference
Summary

Protocol

HTTPS

URI

https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}

Format

JSON

Encoding

UTF-8

API List

API URI Description
Access Token Request https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/token

Requests an access token to request execution of execution unit.

Execution Request https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/run Requests execution of execution unit.
Execution Status Check https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/status Checks execution status of execution unit.
Access Token Request

Requests an access token for requesting execution of execution unit.

The access token has an expiry. If it expires, a new access token is requested.

HTTP Method

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/token

Request Parameters

Parameter Name Value Required Description
krewdataAppUrl Text Required Specifies URL of krewData app registered in the execution unit requested for execution.
serialNumber Text Required Specify the Base64-encoded serial number of real time execution.

Example Request

{
     "krewdataAppUrl": "https://yourdomain.cybozu.com/k/123",
     "serialNumber": "abcdef-jklmno-pqrstu-xyz123-456789"
}

Response

Response code (code), response status (status), and access token (accessToken) are returned if the request is successful. The access token is used in the request parameter of the execution request API and execution status confirmation API.

Parameter Name Value Type Description
code Number Response code. If the request is successful, 200 is returned.
status String Response status. If the request is successful, "OK" is returned.
accessToken String Access Token.

Example Response

{
    "code": 200,
    "status": "OK",
    "accessToken": "abcdefg1234567"
}

Error Response

Response code (code), response status (status), and error message (description) are returned if request is unsuccessful.

Response Code (code) Response status (status) Error Message (description) Description
400 Bad Request krewdataAppUrl data type is wrong, should be string type. A value other than a string is specified for krewdataAppUrl. Specify a string value.
400 Bad Request krewdataAppUrl format is wrong, should be "https://yourdomain/k/appId(/)". The URL format of the specified value of krewdataAppUrl is incorrect. Specify the correct URL format.
Example) https://yourdomain.cybozu.com/k/123
400 Bad Request krewdataAppUrl is empty or krewdataAppUrl cannot be found. Pay attention to the spelling of "krewdataAppUrl". The required item (krewdataAppUrl) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
400 Bad Request Request path is invalid. Requested URL is invalid. Specify a valid URL.
400 Bad Request Request type (Webhook/API) is wrong. The execution method of the requested execution unit is set in the Webhook. Check the steps to execute the execution unit.
400 Bad Request serialNumber data type is wrong, should be string type. A value other than string is specified for serialNumber. Specify a string value.
400 Bad Request serialNumber is empty or serialNumber cannot be found. Pay attention to the spelling of "serialNumber". The required item (serialNumber) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
400 Bad Request serialNumber is not a valid Base64 encoding value. The value specified for serialNumber is not Base64 encoded. Specify a Base64-encoded value.
400 Bad Request Specified krewdataAppUrl is invalid, should be "https://yourdomain.cybozu.com/k/{appId}". The value specified for krewdataAppUrl is incorrect Specify the correct URL for krewData dedicated application where the execution unit that requests for execution is registered.
Example) https://yourdomain.cybozu.com/k/123
400 Bad Request Specified unit is invalid. Execution unit is disabled. Check the following in Real Time Execution tab of the krewData plug-in.
・Execution unit which has requested the access token is Enabled or not.
・Execution unit which has requested the access token has a valid data editing flow registered on it.
400 Bad Request Token request body schema is wrong. The format of the request body is incorrect. Specify the correct format.
401 Unauthorized Illegal License. The serial number specified for serialNumber is invalid. Specify a valid serial number.
429 Too Many Requests The rate limit for API calls has been exceeded. Specified unit has been disabled. The request that exceeds the upper limit of the number of executions within a certain period of time was executed and the execution unit was set to invalid.

Example Error Response

{
    "code": 400,
    "status": "Bad Request",
    "description": "Request path is invalid."
}
Execution Request

Requests execution of execution unit using the access token.

Access token can be used just once in the execution request API. You need to obtain a new access token to call the execution request API again.

HTTP Method

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/run

Request Parameters

Parameter Name Value Required Description
accessToken String Required Specify a valid access token obtained using access token request API.
Access token can be used just once in the execution request API. You need to obtain a new access token to call the execution request API again.
user String Required Specify kintone login name of the user requesting execution of execution unit.
kintone login name specified here is recorded in "Executed by" column of the execution logs.
appId Number or string Required Specify app ID of the Calling App of execution unit to be executed.
record Object Optional Specify record information to be used as parameter of the execution unit.

Example Request

{
    "accessToken": "abcdefg1234567",
    "user ": "krewdata@grapecity.com",
    "appId": "1234",
    "record":{
        "Record Number":{
            "type":"RECORD_NUMBER",
            "value":"1"
        },
        "Date of Arrival":{
            "type":"DATE",
            "value":"2020-11-01"
        },
        ...
    }
}

Response

Response code (code), response status (status), and task ID (taskId) are returned if the request is successful.

Parameter Name Value Type Description
code Number Response code. If the request is successful, 200 is returned.
status String Response status. If the request is successful, "OK" is returned.
taskId String Task ID.

Example Response

{
    "code": 200,
    "status": "OK",
    "taskId": "hijklmn8901234"
}

Error Response

Response code (code), response status (status), and error message (description) are returned if If the request is unsuccessful.

Response Code (code) Response status (status) Error Message (description) Description
400 Bad Request accessToken data type is wrong, should be string type. A value other than a string is specified for accessToken. Specify a string value.
400 Bad Request accessToken is empty or accessToken cannot be found. Pay attention to the spelling of "accessToken". The required item (accessToken) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
400 Bad Request app (appId) is not call app of task specified. The app ID specified by appId is different from the app ID of the "Source App" of the execution unit that requests execution. Specify the app ID of the "Source App".
400 Bad Request appId data type is wrong, should be string type. A value other than a string is specified for appId. Specify a string value.
400 Bad Request appId is empty or appId cannot be found. Pay attention to the spelling of "appId". The required item (appId) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
400 Bad Request record data type is wrong, should be keep with Kintone record. A value that has a different structure from the record information of kintone is specified in the record parameter. Specify in the record information format of kintone.
400 Bad Request Request path is invalid. Requested URL is invalid. Specify a valid URL.
400 Bad Request Run request body schema is wrong. The format of the request body is incorrect. Specify the correct format.
400 Bad Request Specified token has been created for more than 10 minutes and cannot be used to run unit. The specified access token has been expired. Get a new access token with the access token request API
400 Bad Request Specified token has been used. The specified access token has been used. Get a new access token with the access token request API.
400 Bad Request Specified token is invalid. Value specified in accessToken is invalid. Specify a valid access token obtained using access token request API.
400 Bad Request user data type is wrong, should be string type. A value other than a string is specified for user. Specify a string value.
400 Bad Request user is empty or user cannot be found. Pay attention to the spelling of "user". The required field (user) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
409 Conflict Other User is running the execution unit.","taskId":{taskId} Another user is running the execution unit. This execution unit is not allowed to execute concurrently.

Example Error Response

{
    "code": 400,
    "status": "Bad Request",
    "description": "Specified token is invalid."
}
Execution Status Check

Checks execution status of execution unit.

HTTP Method

POST

URI

https://api.krewdata.grapecity.com/trigger/v1/{ExecutionUnitID}/status

Request Parameters

Parameter Name Value Required Description
accessToken String Required Specify a valid access token obtained using access token request API.
taskId String Required Specify the task ID obtained using execution request API.

Example Request

{
    "accessToken": "abcdefg1234567",
    "taskId": "hijklmn8901234"
}

Response

Response code (code), response status (status), execution status of the execution unit (taskStatus), and execution information (flowInfo) of the data editing flow included in the execution unit are returned if the request is successful.

Parameter Name Value Type Description
code Number Response code. If the request is successful, 200 is returned.
status String Response status. If the request is successful, "OK" is returned.
taskStatus String Execution status of execution unit
  • Queuing:Execution is in queue
  • Running:Running
  • Success:Execution completed (Success)
  • Failure:Execution completed (Failure)
errorCode String Error code when taskStatus is Failure
For more information on the error code, refer to the Errors While Executing Data Editing Flow in "Error Messages".
errorMessage String Error message when taskStatus is Failure
For more information on the error message, refer to the Errors While Executing Data Editing Flow in "Error Messages".
flowInfo Object Array Execution information array of data editing flow included in execution unit.
flowInfo.flowExecUniqueKey String Key value that uniquely identifies the executed data editing flow.
flowInfo.flowName String Name of the data editing flow.
flowInfo.status String Execution status of data editing flow
  • Queuing:Execution is in queue
  • Running:Running
  • Success:Execution completed (Success)
  • Failure:Execution completed (Failure)
  • Cancel:Execution is cancelled
flowInfo.startTime String Start date and time of data editing flow.
flowInfo.endTime String End date and time of data editing flow.

Example Response

If the execution unit is running, taskStatus is returned as "Running".

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Running",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "Flow1",
            status: "Running",
            startTime: "2020-12-01 09:00:00",
            endTime: ""
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "Flow2",
            status: "Queuing"
        }
    ]
}

If the execution unit is executed successful, taskStatus is returned as "Success".

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Success",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "Flow1",
            status: "Success",
            startTime: "2020-12-01 09:00:00",
            endTime: "2020-12-01 09:01:00"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "Flow2",
            status: "Success",
            startTime: "2020-12-01 09:01:00",
            endTime: "2020-12-01 09:02:00"
        }
    ]
}

If the execution unit is executed unsuccessful, taskStatus is returned as "Failure". The flowInfo object contains execution result information for each data editing flow.

If an error occurs while running the first data editing flow:

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Failure",
    "errorCode": "33",
    "errorMessage": "The data editing flow settings are incorrect. Correct the error in the data editing flow.",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "Flow1",
            status: "Failure",
            startTime: "2020-12-01 09:00:00",
            endTime: "2020-12-01 09:01:00"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "Flow2",
            status: "Cancel"
        }
    ]
}

If the data editing flow is not executed and an error occurs due to reasons such as concurrent execution of execution unit not being allowed, timeout, etc:

{
    "code": 200,
    "status": "OK",
    "taskStatus": "Failure",
    "errorCode": "134",
    "errorMessage": "Another user is running the execution unit. This execution unit is not allowed to run concurrently. ",
    "flowInfo": [
        {
            flowExecUniqueKey: "12345678",
            flowName: "Flow1",
            status: "Cancel"
        },
        {
            flowExecUniqueKey: "90123456",
            flowName: "Flow2",
            status: "Cancel"
        }
    ]
}

Error Response

Response code (code), response status (status), and error message (description) are returned if the request is unsuccessful.

Response Code (code) Response Status (status) Error Message (description) Description
400 Bad Request accessToken data type is wrong, should be string type. A value other than a string is specified for accessToken. Specify a string value.
400 Bad Request accessToken is empty or accessToken cannot be found. Pay attention to the spelling of "accessToken". The required item (accessToken) of the request parameter is not specified or the value is empty. Specify the parameter and the value.
400 Bad Request Request path is invalid. The requested URL is invalid. Specify a valid URL.
400 Bad Request Specified accessToken is invalid. The value specified for accessToken is invalid. Specify a valid access token obtained by the access token request API.
400 Bad Request Specified taskId is invalid. The Value specified in taskID is invalid. Specify a valid task ID obtained by the execution request API.
400 Bad Request Status request body schema is wrong. The format of the request body is incorrect. Specify the correct format.
400 Bad Request taskId data type is wrong, should be string type. A value other than a string is specified for taskId. Specify a string value.
400 Bad Request taskId is empty or taskId cannot be found. Pay attention to the spelling of "taskId". The required item (taskId) of the request parameter is not specified or the value is empty. Specify the parameter and the value.

Example Error Response

{
    "code": 400,
    "status": "Bad Request",
    "description": "Specified taskId is invalid."
}
Sample Code

Following sample code demonstrates how to place a Run button in Records page of an app and request execution of the execution unit on click of the button.

In this sample code, Run button is placed in the blank area above the menu on the Records page.

Sample Code
Copy Code
(function () {
  'use strict';
  kintone.events.on('app.record.detail.show', function (event) {
    var url = 'https://api.krewdata.grapecity.com/trigger/v1/abcdefghijklmn';
    var krewdataAppUrl = 'https://yourdomain.cybozu.com/k/123';
    var serialNumber = 'abcdef-jklmno-pqrstu-xyz123-456789';
    // Place a "Run" button
    if (document.getElementById('run_button') !== null) {
      return;
    }
    var runButton = document.createElement('button');
    runButton.id = 'run_button';
    runButton.innerText = 'Run';
    runButton.onclick = async(butotnEvent) => {
      if (window.confirm('Execute the krewData execution unit?')) {
        // Request access token
        var tokenBody = {
          'krewdataAppUrl': krewdataAppUrl,
          'serialNumber': window.btoa(serialNumber)
        };
        var tokenResponse = await sendRequest('token', url, tokenBody);
        console.log(JSON.stringify(tokenResponse));
        // Request execution of the execution unit
        if (tokenResponse.code == 200) {
          var accessToken = tokenResponse.accessToken;
          var runBody = {
            'accessToken': accessToken,
            'user': kintone.getLoginUser().code,
            'appId': event.appId.toString(),
            'record': event.record
          };
          var runResponse = await sendRequest('run', url, runBody);
          console.log(JSON.stringify(runResponse));
          // Check status of the execution unit
          if (runResponse.code == 200) {
            var taskId = runResponse.taskId;
            var statusBody = {
              'accessToken': accessToken,
              'taskId': taskId
            };
            var statusInterval = setInterval(async function () {
              var statusResponse = await sendRequest('status', url, statusBody);
              console.log(JSON.stringify(statusResponse));
              if (statusResponse.taskStatus == 'Success' || statusResponse.taskStatus == 'Failure') {
                clearInterval(statusInterval);
              }
            }, 5000); // 5sec
          }
        }
      }
    }
    kintone.app.record.getHeaderMenuSpaceElement().appendChild(runButton);
  });
})();
function sendRequest(api, url, body) {
  var _kintone = kintone;
  var uri = url + '/' + api;
  return new _kintone.Promise(function (resolve, reject) {
    _kintone.proxy(uri, 'POST', {
      'Content-Type': 'application/json;charset=UTF-8'
    }, body, function (body, status, headers) {
      resolve(JSON.parse(body));
    }, function (error) {
      reject(error);
    });
  });
}
See Also