Clarizen connector Update in Jitterbit Design Studio

The Clarizen update activity available within the Clarizen connector allows you to update existing data in a connected Clarizen instance using Jitterbit.

This page describes how to update existing Clarizen data using an example of updating an existing task in Clarizen from source data provided in an XML file through Jitterbit.

This example is used for demonstration purposes only and does not cover all options available in the product; please refer to Design Studio for more comprehensive documentation.

The following sections are divided up into beginning the update activity, defining the operation components, and deploying and executing the operation.

Creating a Clarizen Update operation

1. Within your project within Jitterbit Studio, there are several ways to start a new Clarizen update activity. Each of the following options will start the Clarizen Update Wizard to guide you through the process.

   • Go to File > New > Connectors > New Clarizen Update.
   • In the tree on the left under Connectors, right-click on the Clarizen category, then select New Clarizen Update.
   • In the tree on the left under Connectors, double-click on the Clarizen category, then right-click on Clarizen Update Activities and select New Clarizen Update.
   • In the top toolbar, click the connector icon (orange jigsaw piece) . In the popup, select Clarizen, then select Clarizen Update.

2. The Endpoint screen of the Clarizen Update Wizard should open in the main view of Studio. This screen asks to select the endpoint that you would like to update existing data in. You should have already set up your endpoint in Clarizen connector endpoint. Use the dropdown to select the appropriate endpoint. Click Next when finished.

3. The Object screen of the Clarizen Update Wizard asks you to select the object that you would like to update existing data in. In this example we want to update an existing task in Clarizen, so we select the "Task" object, then click Finish to continue.

   Note

   If you have a lot of objects available in your Clarizen instance, you may need to wait a moment for them to load. You can also enter an object name into the Filter field. Try the Refresh button if the results are not what you expect.

   

4. Jitterbit will then proceed with creating a Clarizen API request and response structure that will allow data to be updated within your connected Clarizen instance. A new tab should appear in Studio called Clarizen Update Activities. You can rename your update activity here if desired; in the example ours is called "Example Clarizen Update Task." You can also use the + - buttons or arrows to expand all elements within each structure.

   

5. Next, on the same screen, click the button Create Operation located under Use in an Integration in the upper right corner. This will create the Jitterbit operation that will update the existing task in Clarizen.

6. A new tab should open in Studio called Operations, containing a graphical representation of the update activity.

   

   Note

   The icons for Source, Request, Response, and Target in the image above are placeholders for the operation components, which we will define in the next section.

   Save your operation by clicking either the single disk icon to save just this operation or the multiple disk icon to save all changes in your integration project. You should see the asterisk on the Operations tab and operation title disappear as your new update activity is now created and saved to your project.

Defining the operation components

Next we need to define the other components of the operation that appear within the graphical representation, including Source, Request, Response, and Target.

For each, the instructions below direct you to return to the graphical representation of the operation you have created and double-click each icon to configure each component. As an alternative, you could also create the Source, Request, Response, and Target separately and then drag and drop them from the tree on the left directly onto the icons in the visual representation of your operation.

For purposes of this walkthrough, we provide the following examples for reference above: Jitterpak ClarizenExample.jpk and accompanying files in ClarizenSampleFiles.zip. Many different types of data can be used for each component of the operation. To learn more about additional customization options, refer to the Design Studio section of our documentation.

• Source: In the example, we use an XML file as the input request to update an existing task with the provided field values below. An ID must be included in the source for an update activity, and can either be the external ID or internal ID (full ID) in the format of /\<object_type>/\<external_id>.

  <ns:INPUT xmlns:ns="urn:czoln:document:czoln:oln:entities">
      <Task>
          <id>jw47joqmno25rh7l5azcmo3o26</id>
          <Name>Testing 123</Name>
          <Description>This is my updated task.</Description>
          </Task>
  </ns:INPUT>
  

  Note

  A Clarizen update activity must use the internal or external ID of the entity within Clarizen in order to associate the update with the correct object. The Clarizen full internal ID includes the entity name in the format of /\<object_type>/\<external_id> (e.g. /Task/jw47joqmno25rh7l5azcmo3o26), while the Clarizen external ID will default to the ID only, e.g. jw47joqmno25rh7l5azcmo3o26.

  Note

  In the example, we use the Clarizen ID returned in the response from the example used in Clarizen connector create where we created Task1. If you are following along with the example you will need to replace this ID with that for the specific task in your Clarizen instance. The update will rename 'Task1' to 'Testing 123' and update the description.

  Note

  A variety of source types are available in Jitterbit. See Sources for more.

  To use the XML file, first double-click on the Source icon, then click the button Create New Source and give your source a Name (e.g. ClarizenUpdate_Task_Request.xml). Next, for this example, we are using a private agent with local files enabled, and thus select a Type of "Local File" and then Browse to the location. If you are using the example files, the Folder is 'C:\ClarizenSampleFiles' and the Get Files is 'ClarizenUpdate_Task_Request.xml'.

• Target: Double-click on the Target icon. In the example, we will output the ID and status of the new task in Clarizen to an XML file to make sure it has been created. Click the Create New Target button, give your target a Name (e.g. ClarizenUpdate_Task_Response.xml), and again select a Type of "Local File" and Browse to a location on the private agent where we want to save the data. In the example, the Folder is 'C:\ClarizenSampleFiles' and the Filename is 'ClarizenUpdate_Task_Response.xml'.

  Note

  You can also output to a variety of different target types. The type does not have to be the same as the source type. See Targets for options.

• Request: Double-click on the Request icon and select Create New Transformation. This will open the Transformation Wizard which will walk you through creating the request.

  Note

  Additional information on request structures is provided under Transformations.

  1. On the first screen, Name, provide a Name for your transformation or leave as the default. Then use the Source dropdown to select "Clarizen Function Request." Click Next to continue.

  2. On the next screen, Source, select the radio button for Update, then click Next. On the following screen, use the dropdown to select the update operation (e.g. "Example Clarizen Update Task"), then click Finish.

  3. The Transformations tab should open where you can complete your mapping. Use the + to expand the source and target items in each tree. Then drag and drop each field you would like to be mapped from one tree to the other. As a shortcut for this example, you can click the auto map icon that appears below the target side of the tree:

     

     Your transformation mapping should look similar to that shown below:

     

• Response: Double-click on the Response icon and select Create New Transformation. This will open the Transformation Wizard which will walk you through creating the response.

  Note

  Additional information on response structures is provided under Transformations.

  1. On the first screen, Name, provide a Name for your transformation or leave as the default. Then use the Target dropdown to select "Clarizen Function Response." Click Next to continue.

  2. On the next screen, Target, select the radio button for Update, then click Next. On the following screen, use the dropdown to select the update operation (e.g. "Example Clarizen Update Task"), then click Finish.

  3. The Transformations tab should open where you can complete your mapping. Use the + to expand the source and target sides. In this example we will create the output response so that it includes the ID, status, and any error messages in the response. Click and drag the "OUTPUT" folder from the left side (source side) to the "OUTPUT" folder on the right side (target side). Your mapping screen should now look similar to that below.

     

Deploying and executing the operation

With the Clarizen update activity fully configured, we are ready to deploy and execute the operation.

1. From the Operations tab, click the deploy icon.

2. Then click the execute icon to place the operation in the queue for execution.

3. In the lower portion of the screen, the Operation monitor should indicate that your operation was run successfully. If not, you can double-click the Status icon to view any log messages.

   

4. You should also now see the output response that was mapped to your target file. In the example, the file is now created in 'C:\ClarizenSampleFiles\ClarizenUpdate_Task_Response.xml'. Since the operation was run successfully, we see the ID of the task in Clarizen and a status of '1' indicating success.

   <ns:OUTPUT xmlns:ns="urn:czoln-res:document:czoln:oln:entities">
       <Task>
           <id>jw47joqmno25rh7l5azcmo3o26</id>
           <status>1</status>
       </Task>
   </ns:OUTPUT>
   

5. In addition, when you check your Clarizen instance, you should find that 'Task1' created during Clarizen connector create is now called 'Testing 123' and the description has been updated.