Skip to content

upsert-limeobject

The upsert-limeobject command creates or updates a limeobject. It can be seen as the perfect match of POST and PUT in the limeobject API! 😻

Change deal title

{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "deal",
        "id": 1001,
        "title": "A big deal"
    }
}

Static parameters

Except for a few static parameter names, parameters used with this command maps directly to the limeproperty. Thus, using the parameter name title maps to the limeproperty on the designated limetype.

System properties beginning with an underscore (_) can't be used

limetype

Required. Specifies the limetype the command maps to.

id

Optional. Specifies an existing limeobject ID to update.

Using this parameter forces an update to occur or an error to be raised if no limeobject matches the given ID.

Can't be used with _target

_target

Optional. Use this constraint to target a limeobject when you don't know the record ID of the limeobject. The command fails when the constraint matches more than one limeobject. The intended use is to target alternate key properties, thus only one property is allowed in the constraint.

Can't be used with id

Important

To succeed with a create or update (upsert) using a target constraint, the property/ies used in the constraint MUST also be given as property values. If not, the command will never match its target constraint and only create limeobjects (never update).

Do

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "order",
        "_target": {
            "erpid": "L337"
        },
        "status": "fulfilled",
        "erpid": "L337"
    }
}

Don't

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "order",
        "_target": {
            "erpid": "L337"
        },
        "status": "fulfilled",
    }
}

_ref

Optional. Use this parameter to give the command a reference ID to be able to use it later in the same batch. This is useful when two connecting two limeobjects created/updated in the same batch, without prior knowledge of their record IDs nor using a persisted alternate key.

Example use case: Creating a deal and a history note in one go (without knowing the record id of the deal to be created).

See Lookup Constraints for example on usage.

Value property parameters

All normal limeobject properties will be mapped by their name from the command.

Example

{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "deal",
        "id": 1001,
        "textproperty": "Value",
        "numberproperty": 123,
        "optionproperty": "optionkey"
    }
}

Relation properties are subject to lookup constraints.

Lookup constraints

In addition to passing the related record ID, relation properties can be set similarly to _target using a lookup. Just like when using a record ID, the lookup MUST return exactly one limeobject of the related limetype. A lookup may only be using a single property for matching the related object.

Lookup syntax:

{
    "relationproperty": {
        "key": "value"
    }
}
key value
Any valid limeproperty Number or string value to match
_ref A reference to another command in the same batch

Example

{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "deal",
        "id": 1001,
        "coworker": 1001
    }
}
Using the record ID similar to a PUT request of the limeobject.

{
    "name": "upsert-limeobject",
    "parameters": {
        "limetype": "deal",
        "id": 1001,
        "coworker": {
            "employee_no": 142
        }
    }
}
Using a limeobject lookup is a convenient alternative to a PUT request since it's not necessary to first GET the related limeobject to figure out its record ID.

{
    "commands": [
        {
            "name": "upsert-limeobject",
            "parameters": {
                "_ref": "fb610927-de9c-427a-8ae9-31890467da84",
                "limetype": "company",
                "name": "Dealicious Ltd."
            }
        },
        {
            "name": "upsert-limeobject",
            "parameters": {
                "limetype": "deal",
                "name": "Awesome magnetic deal",
                "company": {
                    "_ref": "fb610927-de9c-427a-8ae9-31890467da84"
                }
            }
        }
    ]
}
Creating multiple and related objects in one go without knowing their record IDs nor other alternate persisted key properties.

Hint

Matching relations on arbitrary text fields may work, but it's recommended to only use key properties with unique values. Eg. this may work for a while, but would eventually end up in duplicates:

{
    "coworker": {
        "name": "Johan Andersson"
    }
}

Errors

Code Message
PARAMETER "The command parameter(s) are required: missingparameters"
PARAMETER "Invalid limetype: limetype"
PARAMETER "Invalid limeobject limetype:id"
PARAMETER "Access to limetype 'limetype' or a property is denied"
PARAMETER "Parameter names must not begin with underscore (_)"
OTHER "Only one of _target and id parameters can be used"
OTHER "Lookup requires exactly one existing key (field name) and value. Received: lookup"
OTHER "Lookup 'lookup' matched more than one limeobject of type 'limetype'. Lookup must match exactly one record."
Back to top