Lucernex Lookup Keys

The ClientID field is a free form text field that exists for most objects. This field can be used when importing data to uniquely look up a record for update. This lookup key can either be system-generated or defined by the user upon the initial import of record data. A ClientID has the database name BOMapClientRecordID, and its user interface label follows the following naming convention: Object ClientID.

A ClientID is only assignable through import or API call, not through the user interface. A ClientID cannot be changed once it has been assigned. If an object is exported and has no assigned ClientID, the system will assign one. A system-assigned ClientID uses the following naming convention:

• client‐LxID‐DateTimeInMilliseconds

  For example, client‐699209‐1498506974001

<Employer clientID="EMP_12345‐SITE">

RecID fields contain an automatically assigned integer that uniquely identifies each record. A RecID field is also known as a Lucernex ID or an LxID. They are not editable. A RecID has the database naming convention <Object>ID, and its user interface label follows the following naming convention: <Object> RecID.

An object's RecID is what Lucernex uses to link the object to another object.

<Employer lxID="699209">

ClientEntityID fields are editable client-assigned text fields. They are not required to be unique. A ClientEntityID has the database name ClientEntityID, and its user interface label uses the following naming convention: Object ID.

This field exists on the General Entity Info table (ProjectEntity) and in the Summary Information data group > General Summary Information data sub-group. The front-end label of this field in these areas is Store Number.

When added from the General Summary Information data sub-group to a report, Lucernex will automatically grab the appropriate ClientEntityID from the entity type that you are reporting on.

*For ProjectEntity (General Entity Info) table

<Location>
    <ClientEntityID>001253</ClientEntityID>
</Location>

The entity-level ProjectEntityID is system‐assigned, unique, and cannot be edited. The ProjectEntityID field's user interface label is Entity RecID.

This field exists on the General Entity Info table (ProjectEntity) and in the Summary Information data group > General Summary Information data sub-group. The value of the ProjectEntityID is sequential across all entity types. This differs from the entity-type-specific RecID field, which is sequential for a single entity type. For example, the Entity RecID for Location ≠ the Location RecID.

An entity's RecID is what Lucernex uses to link the entity to child objects that can be associated with any entity type. For example, Lucernex links person records to entities using the entity's Entity RecID.

<Location>
    <ProjectEntityID>201253</ProjectEntityID>
</Location>

The entity-level Client Unique ID field is client‐assigned, unique, and cannot be edited after being established. The entity-level Client Unique ID field has the database name MapClientRecordID, and its user interface label is Client Unique ID.

This field exists on the General Entity Info table (ProjectEntity) and in the Summary Information data group > General Summary Information data sub-group. The value of this field is only assignable through import or API call, not through the UI. It can be system‐assigned when the object is exported and has no assigned ClientID. A system‐assigned ClientID uses the naming convention client‐LxID‐DateTimeInMilliseconds—for example, client‐699209‐1498506974001. In this naming convention, the word "client" is literal, and the LxID and DateTimeInMilliseconds are variables populated by the system.

This field is the same regardless of which database table you access it from. For example, if you pull the Client Unique ID for a Location, its value is equal to the Location ClientID.

<Employer clientID="EMP_12345‐SITE">

Entity-level Specific Entity Type Name fields are client‐assigned, unique, and can be edited after being established. The entity-level Specific Entity Type Name fields use the database naming convention Object Name, and their user interface labels are dependent upon the entity type. For example the Specific Entity Type Name for the Site module would have the database name PotentialProjectName, and the user interface label Site Name.

<Location>
    <LocationName>001253 ‐ Pacific Center</LocationName>
</Location>

The entity-level ProjectEntityName field is client‐assigned, unique, and can be edited after being established. The ProjectEntityName field's user interface label is Name. This field's value is the same regardless of which database table you access it from.

For example, if you wanted to report across entity types and include the name of each entity, the ProjectEntityName could be used to pull the entity name regardless of entity type. These entity names would all be listed in one column. For a Location, the ProjectEntityName field's value would be equal to the Location Name, for a Project, its value would be equal to the Project Name, and so forth.

<Location>
    <ProjectEntityName>001253 ‐ Pacific Center</ProjectEntityName>
</Location>

When adding or updating data via API call, if there is more than one lookup key in the call, the system attempts to match record lookup keys in the following order. If the lookup keys included in the call conflict with one another—for example, the RecID refers to record A, and the ClientID matches to record B—the following list displays what happens when these conflicts occur.

• Lookup Keys: RecID, ClientID / Client Unique ID

  • Lookup Key Given Highest Priority: RecID

  • Consequence: there may be a warning returned if you perform multiple calls on the same record but do not specify that you are updating the record. This is because once the ClientID is specified, it cannot be changed.

• Lookup Keys: RecID, [Client] Entity ID

  • Lookup Key Given Highest Priority: RecID

  • Consequence: updates [Client] Entity ID, no warnings

• Lookup Keys: RecID, Entity RecID

  • Lookup Key Given Highest Priority: RecID

  • Consequence: does not update Entity RecID if there is a conflict between lookup keys, no warnings

• Lookup Keys: RecID, Specific Entity Type Name

  • Lookup Key Given Highest Priority: RecID

  • Consequence: attempts to update Name, warns when an entity of same name exists

• Lookup Keys: RecID, Entity Name

  • Lookup Key Given Highest Priority: RecID

  • Consequence: does not update Entity Name if there is a conflict between lookup keys, no warnings

• Lookup Keys: Entity RecID, ClientID / Client Unique ID

  • Lookup Key Given Highest Priority: Entity RecID

  • Consequence: warns when in conflict

• Lookup Keys: Entity RecID, [Client] Entity ID

  • Lookup Key Given Highest Priority: Entity RecID

  • Consequence: updates [Client] Entity ID, no warnings

• Lookup Keys: Entity RecID, Specific Entity Type Name

  • Lookup Key Given Highest Priority: Entity RecID

  • Consequence: attempts to update Name, warns when an entity of same name exists

• Lookup Keys: Entity RecID, Entity Name

  • Lookup Key Given Highest Priority: Entity RecID

  • Consequence: does not update Entity Name if there is a conflict between lookup keys, no warnings

• Lookup Keys: ClientID / Client Unique ID, [Client] Entity ID

  • Lookup Key Given Highest Priority: ClientID / Client Unique ID

  • Consequence: updates [Client] Entity ID, no warnings

• Lookup Keys: ClientID / Client Unique ID, Specific Entity Type Name

  • Lookup Key Given Highest Priority: ClientID / Client Unique ID

  • Consequence: attempts to update Name, warns when an entity of same name exists

• Lookup Keys: ClientID / Client Unique ID, Entity Name

  • Lookup Key Given Highest Priority: ClientID / Client Unique ID

  • Consequence: does not update Entity Name if there is a conflict between lookup keys, no warnings

• Lookup Keys: [Client] Entity ID, Specific Entity Type Name

  • Lookup Key Given Highest Priority: [Client] Entity ID

  • Consequence: attempts to update Name, warns when an entity of same name exists

• Lookup Keys: [Client] Entity ID, Entity Name

  • Lookup Key Given Highest Priority: [Client] Entity ID

  • Consequence: does not update Entity Name if there is a conflict between lookup keys, no warnings

• Lookup Keys: Specific Entity Type Name, Entity Name

  • Lookup Key Given Highest Priority: Specific Entity Type Name

  • Consequence: no warnings

The EmployerName field is client-assigned, editable, and not required to be unique. It has a user interface label of Employer Name.

<Employer lxID="4819256">
    <EmployerName>Realty King</EmployerName>
    <City>Miami</City>
</Employer>

The APVendorNumber is client-assigned, editable, and not required to be unique. It has a user interface label of AP Vendor Number.

Examples:

<Employer>
    <EmployerName>Landlord Limited</EmployerName>
    <APVendorNumber>742‐203941</APVendorNumber>
    <City>Little Rock</City>
</Employer>

When adding or updating data via API call, if there is more than one lookup key in the call, the system attempts to match record lookup keys in the following order. If the lookup keys included in the call conflict with one another—for example, the RecID refers to record A, and the ClientID matches to record B—the following list displays what happens when these conflicts occur.

• The typical lookup key priority is RecID > ClientID > Employer Name > Employer Name + AP Vendor Number.

• However, if you include the match="clientID" attribute in your XML input, Lucernex won’t look further if it fails to find a record with the specified ClientID. Instead, Lucernex will create a new record (POST) or return an error (PUT).

  Copy

  XML Example:

  <Employer clientID="EMP_12345‐SITE" match="clientID">

• If the Employer Name is not found, Lucernex will create a new record (POST) or return an error (PUT). If multiple matches are found, Lucernex will continue with Employer Name + AP Vendor Number.

• If the Employer Name + AP Vendor Number is not found or if multiple records are found, Lucernex will create a new record (POST) or return an error (PUT).