## Overview You can create or update records using the API. If a record with a matching key is found, the record will be updated. If no matching record is found, a new record will be created. ## Limitations 1. You must have "Create" and "Update" permissions for the target "Record". ## Preparation Please [Create an API Key](/manual/api-key) before performing API operations. ## Request Send json data in the following request format: |Setting column|Value| |:--|:--| |HTTP Method|POST| |Content-Type |application/json| |Character Code|UTF-8| |URL|http://{server name}/api/items/{site ID}/upsert(*1)| |Body|Please refer to the json data below| (*1) Please edit the {server name} and {site ID} parts to suit your environment as appropriate. For pleasanter.net, the format is as follows: https://pleasanter.net/fs/api/items/{site ID}/upsert #### Key Column to be Specified Create and update (upsert) records using the API based on the specified key column. Specify the key column using the following parameters. |Property name|Data type|Description| |:--|:--|:--| |Keys| Array (string)| Specify the key column. Multiple column can be specified. | For details, please refer to (a) Single key and (b) Composite key below. #### Insert Image by API You can insert an image into the "「Body」", "「Comment」" and "「Description」" column by specifying an ImageHash in the Body. When updating a record using this function with an update API (update/upsert), the corresponding column of the existing record will be overwritten in the "「Body」" and "「Description」" columns, and added in the "「Comment」" column. In addition, if you specify only ImageHash without specifying Body or DescriptionHash, which specify the string to be registered in the description field in an update API, it will be added rather than overwritten. ##### How to Specify ImageHash <style type="text/css"> .tg {border-collapse:collapse;border-spacing:0;} .tg td{border-color:black;border-style:solid;border-width:1px;font-family:Arial, sans-serif;font-size:14px; overflow:hidden;padding:10px 5px;word-break:normal;} .tg th{border-color:black;border-style:solid;border-width:1px;font-family:Arial, sans-serif;font-size:14px; font-weight:normal;overflow:hidden;padding:10px 5px;word-break:normal;} .tg .tg-0lax{text-align:left;vertical-align:top} </style> <table class="tg"> <thead> <tr> <th class="tg-0lax">1st Level</th> <th class="tg-0lax">2nd Level</th> <th class="tg-0lax">3rd Level</th> <th class="tg-0lax">Description</th> <th class="tg-0lax">Example</th> </tr> </thead> <tbody> <tr> <td class="tg-0lax" rowspan="9">ImageHash</td> <td class="tg-0lax" rowspan="6">Body</td> <td class="tg-0lax">HeadNewLine</td> <td class="tg-0lax">Specify whether to insert a newline at the beginning of the image with true/false. If omitted, there will be no newline.</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">EndNewLine</td> <td class="tg-0lax">Specifies whether to insert a newline at the end of the image with true/false. If omitted, there will be no newline.</td> <td class="tg-0lax">true</td> </tr> <tr> <td class="tg-0lax">Position</td> <td class="tg-0lax">Specifies the position of the image to insert when setting a string in the target item in the same request. If -1 is specified or omitted, it will be inserted at the end.</td> <td class="tg-0lax">3</td> </tr> <tr> <td class="tg-0lax">Alt</td> <td class="tg-0lax">Specifies the string to insert into the alt attribute (text displayed instead of the image when the image cannot be displayed in the web browser). If omitted, "image" will be set.</td> <td class="tg-0lax">hayato</td> </tr> <tr> <td class="tg-0lax">Extension</td> <td class="tg-0lax">Specifies the file extension to register in the Binaries table. If omitted, ".png" will be set.</td> <td class="tg-0lax">.jpeg</td> </tr> <tr> <td class="tg-0lax">Base64</td> <td class="tg-0lax">Specify the Base64 encoded binary data of the image as a string. If you specify ImageHash, this cannot be omitted.</td> <td class="tg-0lax">iVBORw0KG…（the following omitted）</td> </tr> <tr> <td class="tg-0lax">Comments</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionA</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> <tr> <td class="tg-0lax">DescriptionB</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">（same as above）</td> <td class="tg-0lax">-</td> </tr> </tbody> </table> #### Executing Processes via API You can execute a process by specifying the Process ID in the request data. ##### Preconfiguration PLease set up the "「Process」" in advance. ##### Limitations When executing a process via the API, input validation set for the process ##### Process Specifying Method Either ProccessId or ProccessIds should be set. If both are set, ProccessIds is applied. Note that when ProccessIds is set, the specified multiple process IDs will be executed in the order in which they appear in the list of "「Process」" set in advance. |Setting Item|Description|Example| |:--|:--|:--| |ProccessId|Specify the ID of the process.|1| |ProccessIds|Specify IDs for multiple processes.|[1,2,3]| #### (a) Single Key Case Set the name of the key column in the Keys parameter in array format. For the column specified in Keys, search for records that match the value specified in the parameter. In the example below, we search for records whose "ClassA" column value is "RC0001". The following process will be executed depending on the result of the record search. 1. If the target record does not exist: A new record will be created. 1. If one target record exists: That record will be updated. 1. If multiple target records exist: No record will be created or updated and an error response will be returned. ##### JSON ``` { "ApiVersion": 1.1, "ApiKey": "145Afa9AF2A10SafaA21641...", "Keys": [ "ClassA" ], "Title": "Develop new function XX 2", "Body": "Body 2", "CompletionTime": "2018/3/31", "ProcessId": 1, "ClassHash": { "ClassA": "RC0001", "ClassB": "Category 2", "ClassC": "Other 2" }, "NumHash": { "NumA": 100, "NumB": 200 }, "DateHash": { "DateA": "2019/01/01", "DateB": "2020/01/01" }, "DescriptionHash": { "DescriptionA": "Description 2", "DescriptionB": "Overview 2", "DescriptionC": "Supplement 2" }, "CheckHash": { "CheckA": false, "CheckB": true }, "ImageHash": { "Body": { "HeadNewLine": true, "EndNewLine": true, "Position": 3, "Alt": "imageBody", "Extension": ".jpeg", "Base64": "iVBORw0KG..." }, "DescriptionA": { "HeadNewLine": true, "EndNewLine": true, "Position": 3, "Alt": "imageDescriptionA", "Extension": ".jpeg", "Base64": "iVBORw0KG..." } } } ``` #### (b) Composite Key Case If multiple column names are specified in the Keys parameter, the search will look for records that match the values ​​specified in the parameter for all column specified in Keys. In the example below, we search for records where the "ClassA" column value is "RC0002" and the "ClassB" column value is "01". ##### JSON ``` { "ApiVersion": 1.1, "ApiKey": "ad7816s5sD2safFafaD...", "Keys": [ "ClassA", "ClassB" ], "Title": "Develop new function XX 2", "Body": "Body 2", "CompletionTime": "2018/3/31", "ClassHash": { "ClassA": "RC0002", "ClassB": "01", "ClassC": "Other 2" }, "NumHash": { "NumA": 100, "NumB": 200 }, "DateHash": { "DateA": "2019/01/01", "DateB": "2020/01/01" }, "DescriptionHash": { "DescriptionA": "Explanation 2", "DescriptionB": "Summary 2", "DescriptionC": "Note 2" }, "CheckHash": { "CheckA": false, "CheckB": true }, "ImageHash": { "Body": { "HeadNewLine": true, "EndNewLine": true, "Position": 3, "Alt": "imageBody", "Extension": ".jpeg", "Base64": "iVBORw0KG..." }, "DescriptionA": { "HeadNewLine": true, "EndNewLine": true, "Position": 3, "Alt": "imageDescriptionA", "Extension": ".jpeg", "Base64": "iVBORw0KG..." } } } ``` ## Response The json data in the following format will be returned. ##### JSON When a new record is created ``` { "Id": 12345, "StatusCode": 200, "LimitPerDate": 10000, "LimitRemaining": 9994, "Message": "\"Develop new feature XX2\" created." } ``` When a record is updated ``` { "Id": 12345, "StatusCode": 200, "LimitPerDate": 10000, "LimitRemaining": 9994, "Message": "\"Developing new feature XX 2\" updated." } ``` When unable to create or update ``` { "Id": 12345, "StatusCode": 401, "Message": "Authentication failed." } ``` ## Confirmation Column in Case of Error [・Precautions when using the API and things to check if an error occurs](/manual/faq-api) [・FAQ: What to check if modified configuration files or API requests (JSON format) are not recognized correctly](/manual/faq-json-format) ## Specification Changes ***API specifications have been partially changed since October 2019.** - Classification, Numerical Value, Date, Description, and Check Column have been changed from being directly entered in the JSON to being entered within "～Hash". ***API specifications have been partially changed since November 2018.** - The URL format has been changed from '/pleasanter/api_items/xxxx' to '/pleasanter/api/items/xxxx'. - The Content-Type specification has been changed from 'application/x-www-form-urlencoded' to 'application/json'.