HB_API_PATCH command

Sends a PATCH request to the HighBond API.

Syntax

HB_API_PATCH HighBond_API_request_URL HEADERS header_information DATA payload_file PASSWORD num <TO response_file>

Parameters

Name Description
HighBond_API_request_URL

The request details for the HighBond resource.

Include the following details in the request URL:

  • host information, including HighBond region

  • API version number (current major version number)

  • HighBond instance ID (organization ID)

  • HighBond API endpoint name, and any additional endpoint details such as ID number

For example:

"https://apis-us.highbond.com/v1/orgs/11594/robots"

For the request syntax for a specific HighBond resource, see the HighBond API Reference.

HEADERS header_information

The request header information.

In the header, specify the content type of the HighBond API request:

'{"content-type": "application/vnd.api+json"}'
DATA payload_file

The name of the file that contains the request payload.

The request payload is the data that you want to send to HighBond. You contain the data in a JSON file and use DATA to reference the file in the HighBond API request. For guidance on structuring the payload data for a specific HighBond resource, see the HighBond API Reference.

Specify payload_file as a quoted string with a *.json file extension. For example:

DATA "payload.json"

Note

For scripts that you intend to run in Robots, you must also specify a //FILE tag in the analytic header that corresponds to the DATA payload_file parameter. For example:

COMMENT
//ANALYTIC Test HB API commands
//FILE payload.json
END

Location to save the payload JSON file

The location where you save the payload JSON file depends on where you intend to run the script.

Run the script in Analytics

You can save the payload JSON file in the folder containing the Analytics project, or you can save it in a different folder.

If you save the file in a folder other than the project folder, payload_file needs to include a file path with the file name:

DATA "C:\HighBond API payloads\payload.json"

Run the script in Robots

Upload the payload JSON file to the Input/Output tab in the robot that will run the script. The file must be present in the tab before you run the script.

In payload_file, specify the file name only. Do not specify a file path.

PASSWORD num

The password definition to use.

You do not use PASSWORD num to prompt for, or specify, an actual password. The password definition refers to a password previously supplied or set using the PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic tag.

num is the number of the password definition. For example, if two passwords have been previously supplied or set in a script, or when scheduling an analytic script, PASSWORD 2 specifies that password #2 is used.

For more information about supplying or setting passwords, see:

The required password value is a HighBond access token. For more information, see Creating a password definition and specifying a password value.

PASSWORD num may or may not be required, depending on the environment in which the script runs.

Environment where script runs PASSWORD num requirement
Analytics

(online activation)

PASSWORD num is not required.

The current user's HighBond access token, stored in their Windows registry, is automatically used.
Analytics

(offline activation)

PASSWORD num is required.
Robots
TO response_file

optional

The name of the file that contains the request response.

Specify response_file as a quoted string with a *.json file extension. For example:

TO "response.json"

Location to save the response JSON file

The location where the response JSON file is saved depends on where you run the script.

Run the script in Analytics

By default, the response JSON file is saved to the folder containing the Analytics project.

Include a file path with the name to save the file to a different, existing folder:

TO "C:\HighBond API responses\response.json"

Run the script in Robots

If you specify a //RESULT FILE tag in the analytic header, the response JSON file is saved as output with each task run in the robot.

Specify the file name only. Do not specify a file path.

Remarks

Creating a password definition and specifying a password value

When you run a script in Robots that sends a request to the HighBond API, you need to include a password definition with the command that sends the request. The same requirement applies to scripts run in Analytics if you used offline activation.

Regardless of which method you use to create a password definition, the required password value is a HighBond access token, which you can generate in Launchpad. For more information, see Acquire a HighBond access token.

Password definition methods

Method Description

PASSWORD analytic tag

(For scripts that run in Robots)

If you use the PASSWORD analytic tag to create the numbered password definition for connecting to HighBond, no password value is specified in the script. When you create a task to run the script in Robots, an input field in the Task Designer allows you or another user to specify the actual password.

For more information, see PASSWORD analytic tag.

PASSWORD command

(For scripts that run in Analytics, offline activation)

If you use the PASSWORD command to create the numbered password definition for connecting to HighBond, no password value is specified in the script. A password prompt is displayed when the script attempts to connect.

For more information, see PASSWORD command.

SET PASSWORD command

(For scripts that run in Analytics, offline activation)

If you use the SET PASSWORD command to create the numbered password definition for connecting to HighBond, a password value is specified in the script, so no password prompt is displayed. This approach is appropriate for scripts designed to run unattended, but it exposes an actual password in clear text in the script, which may not be appropriate for your situation.

For more information, see SET PASSWORD command.

Acquire a HighBond access token

Caution

The generated access token matches the account used to sign in to HighBond. As a scriptwriter, specifying your own access token in a script may not be appropriate if the script will be used by other people.

Safeguard access tokens like any account password.

Use an existing access token unless you have a reason for creating a new one. If the existing token does not work, create a new one. Using an existing token cuts down on the number of tokens you need to manage.

  1. Do one of the following:

    • From the Analytics main menu, select Tools > HighBond Access Token.

    • In the Script Editor, right-click and select Insert > HighBond Token.

    The Manage API tokens page opens in your browser. You may be required to first sign in to HighBond.

    Access to the Manage API tokens page through Analytics is a convenience feature. You can also sign in to HighBond and access the page through your user profile without using Analytics.

  2. Do one of the following:

    • Use an existing token

      1. In the Token column, click the partially masked token that you want to use.

      2. Enter your HighBond account password and click Confirm.

        The unmasked token is displayed.

      3. Click Copy to copy the token.

        Tip

        Do not close the dialog box containing the token until you have successfully pasted the token.

    • Create a new token

      1. Click Add token > Analytics.

      2. In the New Analytics token side panel, specify the following information:

        Field or option Description
        Description

        Enter a description that provides useful information, such as:

        • The purpose of the token
        • Where the token is used – for example, the name and location of the Analytics script, or the name and location of the robot task
        Token expiry
        • Enabled the token expires after the number of days that you specify
        • Disabled the token never expires

        Note

        Your organization may have a security policy that requires tokens to expire after a certain amount of time. Creating tokens with an expiry is a good practice. HighBond sends you an automated email notification in advance of the expiry date.

        Expires in Specify the number of days before the token expires (1 to 365).
        Password Enter your HighBond account password.

      3. Click Generate token.

      4. Click Copy to copy the token.

        Tip

        Do not close the side panel containing the token until you have successfully pasted the token.

  3. Depending on which password definition method you are using, do one of the following:

    • PASSWORD analytic tag In the Task Designer in an ACL robot, paste the copied token into a password parameter field.

    • PASSWORD command In Analytics, paste the copied token into a password prompt that appears during script execution.

    • SET PASSWORD command In Analytics, paste the copied token at the appropriate point in the SET PASSWORD command syntax in a script.

  4. In Launchpad, close the dialog box or the side panel containing the token.

    If you created a new token, a partially masked version of the token is added to the top of your list of tokens.

    For more information, see Creating and managing HighBond access tokens.