This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

/mergeEntry/{formName}

The details of the Merge operation are tabulated below: 

Merge

DescriptionMerges an existing entry into the indicated form.
URL qualifier

/mergeEntry/{formName}

formName - The form for which an entry is to be created.

MethodPOST
Headers
HeaderValue
Authorizationtoken
Content-Typeapplication/json
(optional) X-AR-Client-TypeClient Type ID
(optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(optional) X-AR-Tiemout

Timeout (in seconds) for REST request

Default value —120 seconds

Request bodyAn entry object in JSON format, merge options and qualification
ReturnsNo body content, but returns HTTP status code 201 with the Location header set to the URL of the new instance resource.
Merge Type

A value that indicates the action to take if the operation includes an Entry ID field and Entry ID that already exists in the target form. This parameter is ignored if you do not specify the Entry ID field or the ID specified does not conflict with existing entry IDs.

Merge TypeDescription
DUP_ERRORGenerates an error.
DUP_NEW_IDCreates a new entry with a new entry ID.
DUP_OVERWRITEDeletes the existing entry and creates a new one.
DUP_MERGEUpdate the fields specified in fieldList in the existing entry.
GEN_NEW_IDAlways generates a new entry ID for the record, even if there is no conflicting entry ID.

Example

Merge entry without attachment field

{
// normal entry values section
    "values" : {
        ...
    },
    // merge options
    "mergeOptions" : {
        "ignorePatterns" : false,
        "ignoreRequired" : false,
        "workflowEnabled" : false,
        "associationsEnabled" : false,
        "mergeType" : "DUP_ERROR",
        "multimatchOption" : 0
    },
    // a String representation of the qualification
    "qualification" : "'8'LIKE \"%match criteria%\"
}

Merge with attachments

DescriptionMerges an existing entry into the indicated form.
URL qualifier

/mergeEntry/{formName}

formName - The form for which an entry is to be created.

MethodPOST
Headers
HeaderValue
Authorizationtoken
Content-Typemultipart/form-data
(optional) X-AR-Client-TypeClient Type ID
(optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
(optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

Request bodyAn entry object in JSON format, merge options and qualification
ReturnsNo body content, but returns HTTP status code 201 with the Location header set to the URL of the new instance resource.
All possible error codes

If the request is not successful, the following error code is returned

500 - Internal Server Error

Example

Merge entry with attachment field

{
    // normal entry values section
    "values" : {
        ...
            AttachmentFieldName : "attachedFileName",
        ...
    },
    // merge options
    "mergeOptions" : {
        "ignorePatterns" : false,
        "ignoreRequired" : false,
        "workflowEnabled" : false,
        "associationsEnabled" : false,
        "mergeType" : "DUP_ERROR",
        "multimatchOption" : 0
    },
    // a String representation of the qualification
    "qualification" : "'8'LIKE \"%match criteria%\"
}

Related topics

ARMergeEntry

Operations on entry objects

Tools for testing the REST API

Login information

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Andrew Hicox

    there is no documentation for the 'mergeOptions' other than the "Merge Type" section, which doesn't even indicate that this goes in the body inside the merge options. So like just trying to infer from the given examples:

    1) ignorePatterns this appears to be boolean, yes? What does it do? I suspect it turns off pattern matching errors like $MENU$ default value and such?

    2) ignoreRequired also appears to be boolean. maybe turns off errors for required fields? If so that's interesting. What happens when I merge a record that does not contain a value for a primary index? How does that work exactly?

    3) workflowEnabled is this a boolean that disables all workflow on the transaction? even DSO? Even merge filters? Inquiring minds would like to know.

    4) associationsEnabled ok. this appears to be the only difference between the "with attachments" and "without attachments" examples? An explanation is in order.

    5) multimatchOption and this is perhaps the most cryptic of all. I suspect this is probably analogous to the "if multiple entries match" option in push-fields filters? The given examples give an enum value ffs. How am I supposed to know what "0" means versus "1"??

    6) qualification yeah ok ... do you mean to tell me that the merge action includes a qualification? Like a push-fields? If so how do I handle what happens when NO records match the qualification?

    May 25, 2018 12:52
    1. Andrew Hicox

      PING! Hello BMC. Are you there?

      Jun 14, 2018 03:47
      1. Andrew Hicox

        good grief. I believe I've solved the mystery of "multimatchOption" at least:

        https://docs.bmc.com/docs/ars91/en/armergeentry-609070921.html

        if it works the same as the C api it's an enum:

        0 = throw an error on multiple matches 1 = use first matching entry

        Jun 14, 2018 03:59
    1. Andrew Hicox

      I have to say, being forced to reverse engineer ARS because the documentation can't be bothered is more than annoying, it's a serious problem. Because I don't REALLY know how this is SUPPOSED to work. The ONLY thing I have to go on is "try this, it seems to do that". How am I supposed to get support on something when I can't know if the product is even doing what it's supposed to do?

      Come ON BMC, the last time this page was updated was 3 years ago

      That being said. For the benefit of future folks looking for anwers here is some of what I've found out today:

      1) if you specify a qualification, the mergeMode appears to be stuck on "overwrite" which means you must specify a COMPLETE record if you're using a qualification

      2) if you specify a qualification that matches an existing record, the API will throw an error unless your 'mergeMode' is not set to "DUP_ERROR". Beyond that, it ignores the mode and does what "DUP_OVERWRITE" mode would do, regardless of what you set it to.

      3) if you specify a qualification AND your 'values' structure contains the 'Entry ID', this value is ignored UNLESS the qualification does not match any existing records

      4) if you specify a qualification that does not match any existing record, AND your 'values' structure contains the 'Entry ID', BUT the 'Entry ID' matches an existing record, it will throw that out and create a new entry id regardless of 'mergeMode'

      can you validate that this is how it's SUPPOSED to work, so that I can count on that behavior being supported going forward?

      Jun 15, 2018 01:06
      1. Fred Grooms

        DUP_MERGE will update a single field if that is what you have in the Values

        My question is what to do if you want to update MULTIPLE records (merge with a qualification)

        Aug 08, 2019 12:42
        1. Anagha Deshpande

          Hello Fred,

          We are working on your query.

          We will respond soon.

          Regards,

          Anagha

          Aug 08, 2019 10:26
          1. Onkar Telkikar

            Hello Fred,

            Apologies for the delay in response.

            Updating multiple records (merge with a qualification) is not supported.

            Regards,
            Onkar

            Mar 24, 2020 10:22
      1. Onkar Telkikar

        Hello Andrew,

        Apologies for the delayed response.

        Please see below the answers to your questions.

        Question: 1) ignorePatterns this appears to be boolean, yes? What does it do? I suspect it turns off pattern matching errors like $MENU$ default value and such?
        Answer: Yes, 'ignorePatterns' is Boolean. It skips field pattern checking (including $MENU$). Correct, it turns off pattern matching errors like $MENU$ default value and such.

        Question: 2) ignoreRequired also appears to be boolean. maybe turns off errors for required fields? If so that's interesting. What happens when I merge a record that does not contain a value for a primary index? How does that work exactly?
        Answer: Yes, 'ignoreRequired' is also Boolean. Correct, it turns off errors for the required fields. It allows NULL in the required fields (not applicable to the Submitter, Status, or Short-Description core fields). Could you please elaborate on your questions: What happens when I merge a record that does not contain a value for a primary index? How does that work exactly?

        Question: 3) workflowEnabled is this a boolean that disables all workflow on the transaction? even DSO? Even merge filters? Inquiring minds would like to know.
        Answer: Yes, 'workflowEnabled' is a Boolean that disables all workflow on the transaction, even DSO and megre filters. Ignore filter processing.

        Question: 4) associationsEnabled ok. this appears to be the only difference between the "with attachments" and "without attachments" examples? An explanation is in order.
        Answer: 'AssociationsEnabled' is also a Boolean. It decides to honor or to dishonor the enforced association.

        Question: 5) multimatchOption and this is perhaps the most cryptic of all. I suspect this is probably analogous to the "if multiple entries match" option in push-fields filters? The given examples give an enum value ffs. How am I supposed to know what "0" means versus "1"??
        Answer: 'multimatchOption' is a flag that determines the action to be taken when there are multiple matching entries for a given query. This parameter is valid only if a query is specified, else the server ignores the parameter.
        The following are the valid values:
        0: Error on multi-match (AR_MERGE_ENTRY_MULT_MATCH_ERROR)
        1: Use first match for the MergeEntry operation (AR_MERGE_ENTRY_MULT_MATCH_USE_FIRST)

        Question: 6) qualification yeah ok ... do you mean to tell me that the merge action includes a qualification? Like a push-fields? If so how do I handle what happens when NO records match the qualification?
        Answer: 'qualification' is a query that determines the set of entries to retrieve. The qualification can include one or more fields and any combination of conditional, relational, and arithmetic (numeric data types only) operations. The system generates an error if the user does not have a read permission for a field or if a field does not exist.

        Regards,
        Onkar 


        Mar 24, 2020 10:52
        1. Onkar Telkikar

          Hello Andrew,

          Apologies for the delayed response.

          Please see below the responses to your comments.

          Comment: 1) if you specify a qualification, the mergeMode appears to be stuck on "overwrite" which means you must specify a COMPLETE record if you're using a qualification
          Response:  Yes.

          Comment: 2) if you specify a qualification that matches an existing record, the API will throw an error unless your 'mergeMode' is not set to "DUP_ERROR". Beyond that, it ignores the mode and does what "DUP_OVERWRITE" mode would do, regardless of what you set it to.
          Response: Correct.

          Comment: 3) if you specify a qualification AND your 'values' structure contains the 'Entry ID', this value is ignored UNLESS the qualification does not match any existing records
          Response: Not correct. If you specify a qualification, the Entry ID is ignored from the qualification.

          Comment: 4) if you specify a qualification that does not match any existing record, AND your 'values' structure contains the 'Entry ID', BUT the 'Entry ID' matches an existing record, it will throw that out and create a new entry id regardless of 'mergeMode'
          Response: Not correct. If you specify a qualification, the Entry ID is ignored from the qualification.

          Regards,
          Onkar



          Mar 24, 2020 11:03