Transferring CxAlloy Issues to Procore Observations
In this article
- How do I use the file?
- What changes do I need to make to the file itself?
- I defined my variables - now what?
As part of a joint effort with Heapy, we wrote a .php script to extract issue data from CxAlloy's API and format it into a request to create observations in Procore. We took that script and created a generic version that anyone can leverage for their own account. This article describes how to use and run that file, as well as some additional modifications that can be made to customize it further.
How do I use the file?
The script was written in PHP, a general purpose programming language for web applications. To open and run the file, a text editor or IDE that supports the execution of .php scripts will need to be used. The script was written using Atom, a free and open-source text and code editor, and the remainder of this document assumes that Atom is the editor being used. However, feel free to use whatever editor you're most comfortable with, as long as it is capable of executing a .php file.
Atom by itself can't execute scripts, but a number of packages have been developed to allow it to do so; the recommended package is called "script". These packages can be easily downloaded from within Atom's interface. After downloading Atom, start the application and press the "Install a Package" button that appears on the Welcome page.
This will open a tab on the left hand side to install packages. Search for "script" and it should be the first result. After installing the package, Atom will be able to execute scripts.
What changes do I need to make to the file itself?
The file requires the following eight variables to run. These variables are defined at the beginning of the script as NULL, and the NULLs should be replaced with the values described below:
- CxAlloy Project ID (int) - The project id in CxAlloy
- Procore Project ID (int) - The project id in Procore
- Initial CxAlloy Issue Status ID (int) - The issue status id in CxAlloy that indicates an issue should be copied into Procore, i.e. the status to look for
- Final CxAlloy Issue Status ID (int) - The issue status id in CxAlloy that the issues should be changed to after being copied, i.e. the status to change to
- CxAlloy API Key Identifier (string) - The CxAlloy key identifier
- CxAlloy API Key Secret (string) - The CxAlloy key secret
- Procore API Key Identifier (string) - The Procore key identifier
- Procore API Key Secret (string) - The Procore key secret
The project and status IDs can be be queried for directly in the API, but they can also be found in the url. It is recommended that users create new statuses to indicate which issues have and haven't been transferred, e.g. "Ready for Transfer" and "Transferred to Procore" as the initial and final status respectively.
For more information on how to generate API keys, refer to CxAlloy and Procore's API documentation:
I defined my variables - now what?
Once the placeholders at the beginning of the file have been defined, the script is ready to run. Open the file in Atom, then press cmd-i. Without any additional modifications, the script will do as follows:
- An observation will be created in Procore for each issue that has the initial status and is located in the specified CxAlloy project
- The CxAlloy issues will have their status updated to the final status
- The script will return a json array containing the list of matching issues in CxAlloy, and the resultant observations in Procore