Skip to main content

InstanceService.GetInstance

Reference​

Prorigo.Protrak.API.Contracts.Instance GetInstance(Guid instanceId, string[] attributes)

Use GetInstance to get details of a Protrak type instance by it's id.

Parameters​

  • instanceId: The unique Guid for a Protrak type instance. In most of the program triggers, the id of the instance being acted upon by user is passed. This id can be used to fetch all the details of one instance.
  • attributes: Array of all attribute names, including standard and custom attributes for which value needs to be fetched in the returned Instance contract. It can be an empty array if no attribute values need to be fetched. For custom attributes, attribute names should be used, not display names.

Returns​

Prorigo.Protrak.API.Contracts.Instance:

  • Guid Id: The instance id
  • string InstanceTypeName: The type name for the instance
  • string Name: The instance Name value (standard attribute)
  • LifecycleState State: Current lifecycle state for the instance
  • Attribute[] Attributes: Array of attribute contracts containing values for attributes passed in attributes parameter.
    • In order for the returned object to have the value, a particular attribute needs to be "visible" in the lifecycle state of the instance. If the attribute is not "visible", the returned array will not contain the attribute name/value element.
    • The attribute value has a CanUpdate property which indicates whether the user has permissions to update value of the attribute in the current lifecycle state.
  • OperationType[] AllowedOperations: Allowed operations for the user who fetched the instance details. These are based on user role and permissions set in lifecycle state.
  • PromoteAction[] AllowedActions: Allowed promote actions for the user who fetched the instance details. These are based on user role and permissions set in lifecycle state promote actions.
  • Lifecycle Lifecycle: Lifecycle contract having details of the lifecycle version associated with the instance.

Caveats​

  • This API returns null if the instance does not exist for the instance Id passed. This should be handled in code where it is not guaranteed that instance with the given id exists.

Usage​

var invoiceAttributes = new string[] { ATTRIBUTE_PATENT_TO_INVC, ATTRIBUTE_AMOUNT_INVOICED };
var invoiceInstance = InstanceService.GetInstance(instanceId, invoiceAttributes);
var invoiceName = invoiceInstance.Name;
var amountInvoiced = invoiceInstance.Attributes.FirstOrDefault(a => a.Name == ATTRIBUTE_AMOUNT_INVOICED);

Troubleshooting​

  • If a particular attribute value is not present in returned Instance contract, confirm that in the current lifecycle version state
    • whether the attribute name is exactly matching the attribute name configured in Schema/Attributes (check for spaces or spelling mistakes)
    • whether the attribute name is present in viewable attributes, or all attributes are marked as viewable
  • If the context user does not have permissions to access the instance, Prorigo.Core.Exceptions.AccessDeniedException is thrown. Based on the business logic, developer may need to catch this exception to handle the scenario.