Lookup Object

Extract information from a Procore object.

This action can be used to execute most Procore API calls that use an HTTP GET request and return a single object (rather than an array of objects). Please refer to the Procore API Reference to find such APIs; most of them begin with the word "Show". Here are just a handful of Procore APIs that you can invoke with this action:

Inputs

Key		Value
`apiPath`	Required	The Procore API endpoint that you wish to invoke, without the "vapid" prefix. Please refer to the Procore Actions overview for more on the `apiPath` input, which is required for all Procore Actions.
`field_<any_string>`	Required (at least one)	The name of a field to be retrieved from the Procore object specified in the `apiPath`. The key can be anything starting with “field_”, while the value must be a Procore field name. To get a list of all possible field names, look at the Responses section of the corresponding Procore API documentation. Any key from the JSON response can be used as a field name. For instance, for the Show Company User API, field names include `address`, `avatar`, `business_phone`, `business_phone_extension`, etc. To reference subfields, use dot notation. For instance, in the Show Company User API, to reference the `name` key within the `vendor` group, you would use “vendor.name”.
`fieldType_<any_string>`	Optional	The data type of the field that was retrieved from Procore using the corresponding `field_<any_string>` input. Only the `date` and `datetime` data types need to be specified in this way. This is necessary to determine which fields should be converted to the specified `timeZone`. Refer to the Responses section of your Procore API's documentation to determine which fields are of type `date` or `datetime`.
`timeZone`	Optional	The time zone in which any `date` or `datetime` fields should be returned. These fields will be converted from the time zone used in the Procore Project to the time zone you specify. If time zone is not specified, all dates/times will be returned in UTC time. See the Zone ID column here for a list of accepted values for the `timeZone` input. This input is unnecessary if no `date` or `datetime` fields are retrieved.

Outputs

Key	Value
`field_<any_string>`	The value retrieved by the corresponding `field_<any_string>` input. So if the key is `field_BusinessPhone`, then this will be the value of the Procore field retrieved by the `field_BusinessPhone` input.

Usage Example

A common purpose of looking up information from a Procore object is to use it to pre-populate some fields in a GoFormz form or other GoFormz object. For this reason, the Lookup action is typically used in conjunction with actions like Create Form, Update Form, Add Data Source Rows, etc. Those actions then reference the outputs of this Lookup Object step.

Suppose you are using a Procore Webhook to dispatch a GoFormz form when a new Incident is created in Procore, and you want to pre-fill this form with some information. One of the fields you want to pre-fill is the name and contact information of the Safety Manager on the project. Here is how you might go about retrieving this data.

Your workflow would start with the Procore Event trigger, which listens for the Procore Webhook to initiate the workflow. Then you might use the Query action to get information about the project's Safety Manager, and the Filter DataSet and Select DataSet Row actions to extract the Safety Manager's user ID from the DataSet file returned by the Query action. After this, you might use this Lookup Object action with the following inputs:

Key	Value
`apiPath`	`/companies/#{trigger.company_id}/users/#{selectSafetyManager.field_contact_id}`
`field_first_name`	`first_name`
`field_last_name`	`last_name`
`field_mobile_phone`	`mobile_phone`
`field_email_address`	`email_address`
`field_job_title`	`job_title`
`field_created_at`	`created_at`
`fieldType_created_at`	`datetime`
`timeZone`	`America/Tijuana`

We use Procore's Show Company User API here. We construct the apiPath as described in the API documentation, using the company ID output from the Webhook trigger and the Safety Manager's user ID from the selectSafetyManager workflow step to fill in the required path parameters.

Next, we retrieve the fields that we want from the user object — first_name, last_name, mobile_phone, email_address, job_title and created_at. Notice that all of these fields can be found in the Responses section of the API documentation. Since the created_at field is a date/time, we specify its field type as such and also specify the time zone in which we want the date and time to be returned.

Finally, you may end your workflow by creating a new form with Create Form and using the information retrieved by this Lookup Object step to pre-fill the Safety Manager's name and contact information in the appropriate form fields.