Skip to main content

InstanceService.CreateInstance

Reference​

Prorigo.Protrak.API.Contracts.Instance CreateInstance(Instance instance)

Use CreateInstance to create a new Protrak type instance with the specified attributes, parent relationships, and lifecycle information.

Parameters​

  • instance: The Instance contract containing all required details for the new instance. This includes:
    • InstanceTypeName: The type name for the instance to be created.
    • Name: The name value for the instance (standard attribute).
    • Attributes: Array of attribute contracts with values for standard and custom attributes. Attribute names should match those configured in the schema.
    • ParentAttributes: (Optional) Array of parent attribute contracts specifying relationships to parent instances. Each parent attribute should include the RelationTypeName and other relevant details.
    • Lifecycle: (Optional) Lifecycle contract specifying the lifecycle version for the instance. If not provided, the default lifecycle for the type is used.

Returns​

Prorigo.Protrak.API.Contracts.Instance:

  • Guid Id: The newly created instance id.
  • string InstanceTypeName: The type name for the instance.
  • string Name: The instance Name value.
  • LifecycleState State: The initial lifecycle state for the instance.
  • Attribute[] Attributes: Array of attribute contracts containing values for attributes set during creation.
  • OperationType[] AllowedOperations: Allowed operations for the user who created the instance.
  • PromoteAction[] AllowedActions: Allowed promote actions for the user who created the instance.
  • Lifecycle Lifecycle: Lifecycle contract for the instance.
  • Other properties as defined in the Instance contract.

Error Handling & Caveats​

  • If the type name or required attributes are missing or invalid, an exception is thrown.
  • If the context user does not have permissions to create the instance, Prorigo.Core.Exceptions.AccessDeniedException is thrown.
  • If the instance name is not unique and the type enforces name uniqueness, an error is returned.
  • If parent relationships are specified, ensure that RelationTypeName and related details are valid and exist in the schema.
  • If attribute values are not compatible with the attribute type (e.g., wrong data type), an error is thrown.
  • If you need to set array or picklist values, ensure the array is not null and matches the schema.
  • Always check the returned instance for expected attribute values and state; if missing, verify attribute names and lifecycle visibility.
  • In batch or scheduler scenarios, always handle exceptions and log errors to avoid silent failures.

Usage​

var newInstance = new Instance {
    InstanceTypeName = "Invoice",
    Name = "INV-2025-001",
    Attributes = new Attribute[] {
        new Attribute { Name = "AmountInvoiced", Type = AttributeType.Numeric, NumericValue = 1000.0 },
        new Attribute { Name = "PatentReference", Type = AttributeType.Text, TextValue = "Patent123" }
    },
    Lifecycle = new Lifecycle { Name = "InvoiceLifecycle" }
};
try {
    var createdInstance = InstanceService.CreateInstance(newInstance);
    var instanceId = createdInstance.Id;
} catch (AccessDeniedException ex) {
    // Handle permission errors
} catch (Exception ex) {
    // Handle validation or schema errors
}

Example: Creating a Due Date Instance in a Scheduler​

var dueDateInstance = new Instance {
    InstanceTypeName = "DueDate",
    Attributes = new Attribute[] {
        new Attribute { Name = "DueDate", Type = AttributeType.Date, DateValue = finalDueDateValue },
        new Attribute { Name = "Status", Type = AttributeType.Picklist, TextValue = "Scheduled" }
    }
};
try {
    InstanceService.CreateInstance(dueDateInstance);
} catch (Exception ex) {
    // Log and handle errors, e.g., missing required attributes or invalid values
}

Troubleshooting​

  • If the returned Instance contract does not contain expected attribute values, verify that attribute names match the schema and are set as visible in the lifecycle state.
  • If an exception is thrown, check for missing required fields, invalid type name, or insufficient permissions.
  • If the instance is not created, ensure that the name is unique (if required) and parent relationships are valid.
  • For batch/scheduler programs, always log errors and consider retry logic for transient failures.