Skip to end of metadata
Go to start of metadata

Introduction

A ServiceMax bulk insert activity interacts with a ServiceMax connection to insert a large number of new records as a target in an operation, while a ServiceMax bulk upsert activity interacts with a ServiceMax connection to update a large number of existing records as a target in an operation. After configuring a ServiceMax connection, you can configure as many ServiceMax activities as you like for each ServiceMax connection.

The bulk insert and update activities are faster and scale better than non-bulk ServiceMax insert and update activities, but should be used only if you do not need to use a transformation to change data prior to reaching its target. (ServiceMax bulk activities cannot be used with transformations.)

The bulk insert activity is used to create new records, while the bulk update activity is used to update records that already exist based on the ID of the object in ServiceMax. If instead you want to use an external ID field to (1) bulk insert records if they do not already exist, as well as (2) bulk update records if they already exist, use a ServiceMax bulk upsert activity.

NOTE: Cloud Studio supports Salesforce API version 47 from the Salesforce Winter '20 release.

Creating a ServiceMax Activity

From the design canvas, open the Connectivity tab of the design component palette:

Within the Endpoints filter, click the ServiceMax connection block to display activities that are available to be used with a ServiceMax connection:

To create an activity that can be configured, the activity must first be added to an operation on the design canvas. To add an activity to an operation, drag the activity block from the palette to the operation.

For more information about the parts of an operation and adding activities to operations, see Operation Creation and Configuration.

Accessing Menu Actions

After a ServiceMax activity has been added to an operation, menu actions for that activity are accessible from the project pane in both the Workflows and Components tabs, and from the design canvas:

  • Project Pane: In the Workflows or Components tab of the project pane, hover over an activity name and click the actions menu icon  to open the actions menu.

  • Design Canvas: Within the operation, click an existing activity block to open the actions menu.

Each of these menu actions is available:

  • View/Edit: This opens the activity configuration screen for you to configure the activity. For details, see Configuring a ServiceMax Bulk Insert or Update Activity later on this page.
  • Delete: This is used to permanently delete the activity (see Component Dependencies, Deletion, and Removal).
  • Rename: This positions the cursor on the activity name in the project pane for you to make edits.
  • View Dependencies: This changes the view in the project pane to display any other parts of the project that the activity is dependent on (see Component Dependencies, Deletion, and Removal).
  • Remove: Available only from the actions menu on the design canvas, this removes the activity as a step in the operation without deleting it from the project. When you remove an activity that is adjacent to a transformation, if schemas are provided within that activity, they will no longer be referenced by the transformation. Removed components can be accessed or permanently deleted from the project pane (see Component Dependencies, Deletion, and Removal).
  • Deploy: This deploys the activity and any components it is dependent on (see Component Deployment).
  • Configurable Deploy: This opens the deployment screen, where you can select project components to deploy (see Component Deployment).
  • Add to group: This opens a prompt to create a new custom group or to add the component to an existing group. Custom groups are an organizational tool to help organize a project (see Component Groups).
  • Duplicate: This creates a copy of the activity as a new, unreferenced component. Upon creating the component copy, the cursor is positioned on the component name within the project pane for you to rename the component.

Configuring a ServiceMax Bulk Insert or Update Activity

The steps to configure a ServiceMax bulk insert or bulk update activity are the same. Follow these steps to configure either of these activities:

Step 1 – Enter Basic Information and Select Object

  • Name: Enter a name to use to identify the ServiceMax activity. The name must be unique for each ServiceMax bulk insert or bulk update activity and must not contain forward slashes (/) or colons (:).
  • Select the Object Reference: Use the dropdown to select a ServiceMax standard or custom object to bulk insert or bulk update. Enter any part of the object name into the search box to filter the list of objects. The search is not case-sensitive.

    TIP: If the dropdown does not populate with available objects, the ServiceMax connection may not be successful. Ensure you are connected by reopening the connection and retesting the credentials.
  • Refresh: Click the refresh icon  to reload objects and fields from the ServiceMax endpoint. This may be useful if you have recently added objects or fields to the ServiceMax instance.
  • Save & Exit: If enabled, click to save the configuration for this step and close the activity configuration.
  • Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

Step 2 – Provide the Response Schema

  • Provide Response Schema: The response schema defines the structure of response data that will be used by the ServiceMax bulk activity. This response schema will be used as part of the ServiceMax bulk activity for creating mappings in the next step. Select from one of two options below.

    NOTE: Schemas for ServiceMax bulk activities are always part of the activity and can never be defined in a transformation, as transformations cannot be used in an operation that has a ServiceMax bulk activity.
    • Use Saved Schema: Choose this option to select an existing file schema that has previously been defined in the current project.
      • Saved Schemas: Use the dropdown to select from an existing schema to reuse.

      • View/Edit Schema: After an existing schema is selected, you can view or edit it directly within the text area below the dropdown.

      • Validation: As you edit a schema, validation information will be provided below the text area, with any errors reported one line at a time. That is, after resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Validation is based on the file extension of the saved schema.

        WARNING: If you have edited a saved schema, a popup will ask you to acknowledge that the edits will affect other areas of the project where the saved schema is used. If you click Continue, the edits will take effect everywhere the schema is used in the project. If you don't want to affect other areas where the saved schema is used, click Cancel and provide a new schema instead.

    • Provide New Schema: Choose this option to define a new schema by uploading a file or manually entering one into the text area.
      • Schema Name: Enter a name for the schema into the upper text box, including the .csv file extension. If no file extension is provided, the file will be treated as CSV by default. If you will be uploading a file, you can leave this blank, as the name will be populated once the file is loaded.

      • Upload File: Click this button to open a window where you can load a schema from a file that is accessible from the current machine:

        • File: Use the Browse button to the right to browse to a CSV file that has not yet been used in the current project. Files up to 5 MB in size can be uploaded.

          WARNING: If you try to upload a file with the same name as an existing file already defined in the project, a popup will ask if you want to overwrite the existing file. If you click Continue, the file will be replaced with the new file with the same name in all places where it is used in the project. If you don't want to overwrite the file, click Cancel and then manually modify the file so it has a name that is not already being used, then try to upload it again.

        • Load:Click this button to load the schema from the file. Note that some data may be converted during processing as described in Schema Processing.
        • Cancel: Click Cancel to close the Upload Schema File window without saving.
      • View/Edit Schema: After a schema is loaded, you can view or edit it directly within the text area below the Upload File button. Another option is to manually enter or paste a schema into this area without loading a schema from a file.
      • Validation: As you edit a schema, validation information will be provided below the text area, with any errors reported one line at a time. That is, after resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Validation is based on the file extension of the provided schema.
  • Back: Click to temporarily store the configuration for this step and return to the previous step.
  • Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

Step 3 – Map Headers

  • Map Headers: This step is used to map fields by column in the source file to those in the ServiceMax bulk target activity. To complete a mapping, drag a source field on the left to a target field on the right. When fields are mapped, the background becomes orange and a line is drawn between the mapped fields. To remove a mapping, click on either the source field or target field.
    • Source File Headers: The left side shows the headers for the columns in the CSV file provided in the previous step.
      • Search: Enter any part of the header name into the search box to filter the list of headers. The search is not case-sensitive.
      • Import Mapping: To import a mapping that has previously been exported, click the Import Mapping link, then provide input in the popup:

        • File Type: Use the dropdown to select the format of the mapping file:
          • JDL: Select JDL to use a file that has been exported from a Design Studio bulk process operation (from the Design Studio option to Save Mappings to File described in Salesforce Bulk Process Wizard).
          • JSON: Select JSON to use a file that has been exported from Cloud Studio using the Export Mapping link described below.
        • File: Click the Browse button on the right to select a file that contains the mapping.
        • Upload: After selecting a file, click Upload to upload the mapping.

          WARNING: The uploaded mapping will overwrite any existing mappings, if present.
        • Cancel: Click Cancel to close the import dialogue without uploading a mapping.
      • Export Mapping: To export an existing mapping, click the Export Mapping link. This will initiate the download process in your browser. The exported file will be in JSON format. Each field mapping will include the source field name, target field name, and source index.

        NOTE: Exported bulk activity mappings cannot be imported as transformation mappings and can be imported only using the Import Mapping link described above.
    • ServiceMax Fields: The right side shows the column names in ServiceMax that are available to be mapped to. 
      • Search: Enter any part of the column name into the search box to filter the list of headers. The search is not case-sensitive.
      • Automap: Click the Automap link to map source and target field names that are exact match (regardless of case) and have identical data types. Fields that are automapped will be in addition to any existing mappings, which will be left in place.
      • Start Over: Click the Start Over link to clear all mappings.
  • Back: Click to temporarily store the configuration for this step and return to the previous step.
  • Finished: Click to save the configuration for all steps and close the activity configuration.
  • Discard Changes: After making changes, click Discard Changes to close the configuration without saving changes made to any step. A message will ask you to confirm that you want to discard changes.

Next Steps

After configuring a ServiceMax bulk insert or update activity, you can use it within an operation as described below. In addition, if you are running into record limits imposed by the API, you may want to use chunking.

Completing the Operation

After configuring a ServiceMax bulk insert or bulk update activity, complete the configuration of the operation by adding and configuring other activities or scripts as operation steps (see Operation Creation and Configuration). You can also configure an operation's operation settings, which include the ability to chain operations together that are in the same or different workflows (see Operation Settings).

ServiceMax bulk insert or update activities can be used as a target with this operation pattern:

A ServiceMax activity can be used as an operation step in only a single operation. That is, you cannot reference the same activity multiple times within other operations. Instead, you can make a copy of a ServiceMax activity to use elsewhere (see Component Reuse).

Other patterns are not valid using ServiceMax bulk insert or update activities. See the validation patterns on the Operation Validity page.

This example setup depicts one common operation setup using a ServiceMax bulk insert or bulk update activity:

In addition, the file-based source used in the operation must be using a CSV file format with a header and only these data types:

  • Base64
  • Boolean
  • Date formats
  • Double
  • Integer
  • ServiceMax ID
  • String

Operations that use ServiceMax activities can also have operation actions configured to trigger upon a SOAP fault — an error resulting from an incorrect message format, header processing, or incompatibility. Operation actions can be configured to run an operation or send an email after a SOAP fault occurs. For instructions on triggering an action upon SOAP fault, refer to Operation Actions.

When ready, deploy and run the operation (see Operation Deployment and Execution) and validate behavior by checking the operation logs (see Operation Logs).

Using Chunking

Many web service APIs have size limitations. If you are running into record limits imposed by the API, you may want to use chunking to split the source data into multiple chunks. The transformation is then performed on each chunk separately, with each source chunk producing one target chunk. The resulting target chunks combine to produce the final target.

When using chunking with ServiceMax bulk activities, it is recommended to change the default chunk size of 200 to a large number, such as 10,000.

For instructions and best practices on using chunking, see Operation Options.

On This Page

Last updated:  Jan 17, 2020

  • No labels