Single Select Lookup > REST Service

Background and Setup

Examples

Prerequisites

AgilePoint NX OnDemand (public cloud), or AgilePoint NX PrivateCloud or AgilePoint NX OnPremises v7.0 Software Update 2 or higher.

Good to Know

Some information about third-party integrations is outside the scope of the AgilePoint NX Product Documentation. It is the responsibility of the vendors who create and maintain these technologies to provide this information. This includes specific business use cases and examples; explanations for third-party concepts; details about the data models and input and output data formats for third-party technologies; and various types of IDs, URL patterns, connection string formats, or other technical information that is specific to the third-party technologies. For more information, refer to Where Can I Find Information and Examples for Third-Party Integrations?

How to Start

On the Single Select Lookup form control configuration screen, on the Configure tab, click Add Lookup.
For information about how to open this screen, refer to Single Select Lookup form control.
On the Select Data Source Type screen, select REST Service.
Click Next.

Lookup Details

Specifies the basic configuration for a lookup.

Fields

Field Name	Definition
Advanced Configuration	Description: Specifies if you want to do a detailed configuration of the REST service. Allowed Values: Deselected - Does not do a detailed configuration of the REST service. Selected - Does a detailed configuration of the REST service. Default Value: Deselected
Access Token	Description: Specifies the access token that connects to your data source. Allowed Values: A list of access tokens configured for your environment. Default Value: None Accepts Variables: No Example: Refer to: (Example) Create a REST Service Access Token
Add New	Opens this Screen: Access Token for REST Service Function of this Screen: Configure an access token to connect to a REST service. Example: Refer to: (Example) Create a REST Service Access Token
Lookup Name	Description: Specifies the name you want to give to your lookup procedure. Allowed Values: One line of text (a string). Accepted: Letters Numbers Spaces Default Value: None Accepts Variables: No Example: Refer to: (Example) How Do I Configure a Pop-Up Select Control to Bind the Lookup Values to a Data Grid? (Example) Configure an Auto-Lookup Form Control with Microsoft Excel
Lookup Type	Description: Specifies the Name/Value type for the lookup procedure. The Single Select Lookup form control does not support Multiple Columns lookups. If you select the Multiple Columns, the configuration screen shows Name/Value lookup type. Allowed Values: Read only. Default Value: Name/Value

Configure Lookup > Advanced Configuration tab

Configures a lookup in details for the REST service.

Fields

Field Name	Definition
Request URL	Description: Specifies the REST service URL for your method. Allowed Values: A valid REST service URL. Default Value: None
Action	Description: Specifies the type of action for the REST service to do. Allowed Values: POST GET DELETE PUT PATCH Default Value: GET
Content Type	Description: Specifies the type of content the REST service uses. JSON or XML patch files are also supported to patch the document with the specified changes. Allowed Values: XML JSON x-www-form-urlencoded Default Value: JSON
Accept	Description: Specifies the data format to accept in a REST service. Allowed Values: XML JSON x-www-form-urlencoded Default Value: JSON
Protocol	Description: Specifies the communication protocol for your REST service. Allowed Values: HTTP 1.0 HTTP 1.1 Default Value: None
Request Timeout (sec)	Description: Specifies the maximum amount of time, in seconds, to complete the REST service call for the activity. Allowed Values: An integer. Represents: A number of seconds Default Value: 60
Read-Write Timeout (sec)	Description: Specifies the maximum amount of time, in seconds, for read and write methods. Allowed Values: An integer. Represents: A number of seconds Default Value: 60
Header Information	Description: Specifies the custom headers for the REST service. Request headers are usually used to give security information, such as authentication credentials. Allowed Values: Name Value Default Value: None Accepts Variables: Yes
Add Header	Description: Specifies the header name and value to add in the Header and Value field.
Authentication	Opens this Screen: Advanced Configuration > Authentication screen > Basic Authentication tab - Creates REST service authentication credentials to connect to a REST service URL with basic authentication. Advanced Configuration > Authentication screen > OAuth 2.0 tab - Creates REST service authentication credentials to connect to a REST service URL with the OAuth 2.0 protocol. Advanced Configuration > Authentication screen > Windows Authentication tab - Creates REST service authentication credentials to connect to a REST service URL with Windows Authentication (NTLM).

Configure Lookup > Basic Authentication tab

Creates REST service authentication credentials to connect to a REST service URL with basic authentication.

Fields

Field Name	Definition
User Name	Description: Specifies the user name for REST service authentication. Allowed Values: A valid user name. Default Value: None Example: Refer to: (Example) Create a REST Service Access Token
Password	Description: The password for the authentication account. To Open this Field: On the SFTP Access Token screen, click Password Authentication. Allowed Values: An alphanumeric string that represents a password. Default Value: None Accepts Variables: No
Authorization	Description: Specifies an authorization value to connect to the REST service. Allowed Values: A valid authorization value. When you click Generate button, this field completes. Default Value: None
Generate	Function: Gives the authorization value to connect to the REST service.
Insert	Function: Adds the authorization name and value in the Header and Value field.
Reset	Description: Deletes the REST service authentication credentials.

Configure Lookup > OAuth 2.0 tab

Creates REST service authentication credentials to connect to a REST service URL with the OAuth 2.0 protocol.

Fields

Field Name	Definition
Token Type	Description: Specifies the name of an external system, such as SharePoint, Google Drive, or Box from the list. Allowed Values: The name of an external system. Default Value: None
Token	Description: Specifies the access token for the specified external system. Allowed Values: An access token from the list. Default Value: None. When you select an external system from the Token Type field, the name of the access token for the specified system shows in this field.

Configure Lookup > Windows Authentication tab

Creates REST service authentication credentials to connect to a REST service URL with Windows Authentication (NTLM).

Fields

Field Name	Definition
Domain	Description: The domain for the REST service authentication. Allowed Values: A valid domain. Default Value: None
User Name	Description: Specifies the user name for the REST service authentication. Allowed Values: A valid user name. Default Value: None
Password	Description: The password for the authentication account. Allowed Values: An alphanumeric string that represents a password. Default Value: None Example: Refer to: (Example) Create a REST Service Access Token

Configure Lookup > Request tab

Configures the request payload for the REST service method call.

Fields

Field Name	Definition
Request Payload	Description: Specifies your payload values in the box. The values of the payload must be in JSON/XML format. Allowed Values: JSON XML Default Value: The value specified in the XML/JSON Payload field of the access token.
Map Schema	Opens this Screen: Schema Mapper Function of this Screen: Maps SharePoint fields, form fields, web methods, or other input sources to an XML schema.. Example: Refer to: (Example) Schema Mapper

Configure Lookup > Response tab

Connects the response data from the Oracle NetSuite call to your app.

Field Name	Definition
Store the Response in Form Field	Description: Specifies the variable that stores the response to a method call. The method calls a REST service. This field is applicable only for Multiple Columns lookup type. Allowed Values: A process data variable. Default Value: None Accepts Variables: Yes
Enter Sample Response	Description: Specifies sample response schema to connect to your process. Allowed Values: Selected - Configures sample response schema to connect to your process. Deselected - Configures a response schema with a simulation. Default Value: Selected
Header (Optional)	Description: Specifies the custom headers for the REST service Allowed Values: Name - Specifies a name of the custom header. Value - Specifies a value to use for the custom header. Default Value: None
Add New Record	Function: Adds the row for Name and Value fields. To Open this Field: On the Configure Lookup screen, in the Response tab, select Enter Sample Response.
Update	Function: Updates the row with Name and Value fields. To Open this Field: On the Configure Lookup screen, in the Response tab, click Add New Record.
Delete	Function: Deletes the row with Name and Value fields. To Open this Field: On the Configure Lookup screen, in the Response tab, click Update.
Edit	Function: Changes the row with Name and Value fields. To Open this Field: On the Configure Lookup screen, in the Response tab, click Update.
Sample JSON/XML	Description: Specifies an example response payload to connect the process schema in JSON or XML format. Allowed Values: Sample payload data in XML or JSON format. Default Value: None
Payload	Description: Specifies JSON or XML response payload to connect to the process schema. Allowed Values: XML JSON x-www-form-urlencoded Default Value: JSON
Simulate	Opens this Screen: REST Response Configuration > Simulate To Open this Field: On the Configure Lookup screen, in the Response tab, click Get Response from Simulation. Function of this Screen: Configures the response settings with a simulated REST method call.
Map Schema	Opens this Screen: Schema Mapper Function of this Screen: Maps SharePoint fields, form fields, web methods, or other input sources to an XML schema.. Example: Refer to: (Example) Schema Mapper

Configure Lookup > Error Messages tab

Configures the message to show if the lookup does not return any data.

Fields

Field Name	Definition
No Items Retrieved	Description: Specifies the error message to show if the lookup does not return any data. Allowed Values: One line of text (a string). Accepted: Letters Numbers Spaces Default Value: None
Lookup Failed	Description: Specifies the message to show if the data fails to load. Allowed Values: More than one line of text. Default Value: Failed to load data.