VarRecord

Description

A VarRecord is any record that has variable fields. In other words, it represents any primary or auxiliary item. The item's fields are not defined by the database schema. They are configured dynamically by the SBM administrator. VarRecord objects require a table ID at creation, so they cannot be created with CreateObject(). Use Ext.CreateVarRecord().

Inheritance

AppRecord->VarRecord

Methods

• GetDisplayIssueId(): Returns the item's display ID, consisting of a prefix indicating the item's type and a serial number within the item's project. Item types and their prefixes are defined when an SBM designer configures a workflow. See GetItemNumber() and GetItemPrefix() for the components of the display ID.

  Input: N/A

  Output: N/A

  Return: (string) – The item's display ID.

• GetFieldValue(name, value [, fieldList [, field] ]): Gets the value of a field in the calling record's variable field list. The "fieldList" and "field" parameters are optional. If supplied, they can boost efficiency for repeated calls to GetFieldValue() and SetFieldValue(). Note that fields not contained in a variable field list (i.e., system table fields) cannot be accessed with this method.

  Input: name (string) – The name of the field whose value will be retrieved from the calling record's variable field list.

  Output: value (string) – The internal value for the field. For Text fields, this is the exact value entered in the field.

  Note: If the field is a Multi-User field for which the Groups and Users selection mode is enabled, the value can include both pure integers (TS_IDs from the TS_USERS table) and group identifiers (TS_IDs from the TS_GROUPS table). The latter are in the form G1, G2, …

  Input/Output: fieldList (VarFieldList) – Optional. If supplied and equal to the global constant Nothing, this parameter will refer to the calling record's VarFieldList when this method returns. If supplied and not equal to Nothing, this parameter is taken to be the calling record's VarFieldList. Do not set this parameter's value yourself. Always pass a variable set to Nothing and then reuse the variable for subsequent calls to GetFieldValue() and SetFieldValue() on the same VarRecord object. If this parameter is omitted, no functionality changes, but efficiency may suffer.

  Input/Output: field (Field) – Optional. If supplied and equal to the global constant Nothing, this parameter will refer to the Field object on the calling record's VarFieldList whose name matches the "name" input parameter when this method returns. If supplied and not equal to Nothing, this parameter is taken to be that Field object. As with the fieldList parameter, you should never set this value yourself. Always pass a variable equal to Nothing and reuse the variable in subsequent calls to GetFieldValue() and SetFieldValue() on the same VarRecord object and the same value for the "name" input parameter. Passing this parameter only affects the efficiency of repeated GetFieldValue() and SetFieldValue() calls.

  Return: (bool) – True if the named field was found in the calling record's VarFieldList and its value was successfully retrieved.

  Example:

  var value = Variant();
  var fieldList = Variant();
  var field = Variant();
  fieldList = Nothing;
  field = Nothing;
  //  Create and retrieve Contact record
  var tableId = Ext.TableId ("TS_CONTACTS");
  var myRecord = Ext.CreateAppRecord (tableId);
  var whereClause = "TS_CONTACTFIRSTNAME like 'Joe'";
  var ok = myRecord.ReadWithWhere (whereClause);
  //  If no e-mail address, supply default value
  if ( ok ) {
      ok = myRecord.GetFieldValue ( "EMAIL", value, fieldList, field);
  }
  if ( ok && value == "" ) {
      ok = myRecord.SetFieldValue ( "EMAIL", "joe@company.com", fieldList, field);
  }
  if ( !ok ) {
      Ext.LogErrorMsg ("Error in Joe's Email field");
  }

  Note: A GetFieldValue method is also included in the SBM JavaScript Library.

• GetItemNumber(): Returns the numeric portion of the item's display ID. See GetDisplayIssueId() for entire display ID.

  Input: N/A

  Output: N/A

  Return: (long integer) – numeric portion of the item's display ID.

• GetItemPrefix(): Returns the prefix of the item's display ID, indicating the item's type. Item types and their prefixes are defined when an SBM designer configures a workflow. See GetDisplayIssueId() for entire display ID.

  Input: N/A

  Output: N/A

  Return: (string) – prefix of the item's display ID.

• GetStateId(): Identifies the calling record's state within a workflow.

  Input: N/A

  Output: N/A

  Return: (long integer) – TS_ID of the record's state within the item's workflow. If the record is not from a primary table, then it does not have a workflow and the return value is -1.

• SetFieldValue( name, value [, fieldList [, field] ]): This method is identical to GetFieldValue(), except the "value" parameter is for input, as follows:

  Input: value (string) – A value in internal database format to be written to the named field in the calling record's VarFieldList. Field names for variable fields should be provided in upper case for database column names (TITLE, for example) or in lower or mixed case for display names (Title, for example). For details on working with different types of database fields, refer to Working with SBM Database Fields.

  Note that if the field is a journal field, consider using the Field function AppendJournalText to add a single journal entry.

  Note: A SetFieldValue method is also included in the SBM JavaScript Library.

• StartTransition( trans [, bool stealLock ] ) (On-premise only): Starts a transition on an item.

  Input: trans (string) – Can be transition ID, 0 (will use default Update transition for item), transition UUID, or transition internal name.

  Input: stealLock (bool) – If true, any item lock on this item will be stolen by this transition. If it was locked, the user who had the item locked (in transition) will not be able to complete their transition. Does not guarrantee transitions success, as scripts can steal locks from each other.

  Return: (bool)

  Note the following:

  • VarRecord must have been read before invoking this.
  • StartTransition is not required, script can simply invoke QuickTransition if all required field values have already been set on the item. StartTransition will initialize fields as if the transition form has been opened on the end user interface. Fields will resond correctly to GetRequiredFlag.
  • Sets Shell.LastErrorMessage on error (returns false).
  • Locks item, use AppRecord->Unlock if you do not wish to complete the transition. Re-read item to get it re-initialized if transition is not desired to be completed.

  Example:

  var varRecord = Ext.CreateVarRecord( tableId );
  var read =  varRecord.Read( itemTitle );
  var started = varRecord.StartTransition( transitionId );

• StartTransitionWithLock( trans [, bool stealLock ] ) (On-premise only): Identical to StartTransition, except designed to work with AppRecord's Lock function. Finish transition should Unlock the item.

  Return: (bool)

  Example:

  var varRecord = Ext.CreateVarRecord( tableId );
  var read =  varRecord.Read( itemTitle );
  var gotLock = varRecord.Lock( "True" );
  var transLockStarted = varRecord.StartTransitionWithLock( transId, "True" );

• FinishTransition( trans [, bool stealLock ] [, signedUserID, signedUserPwd ] ) (On-premise only): Finishes a transition on an item.

  Input: trans (string) – Can be transition ID, 0 (will use default Update transition for item), transition UUID, or transition internal name.

  Input: stealLock (bool) – If true, any item lock on this item will be stolen by this transition. If it was locked, the user who had the item locked (in transition) will not be able to complete their transition. Does not guarrantee transitions success, as scripts can steal locks from each other.

  Input: signedUserID, signedUserPwd – If the transition requires user signature, this is a way to provide the signature.

  Return: (bool)

  Note the following:

  • VarRecord must have been read before invoking this.
  • StartTransition should have been invoked. See notes on StartTransition.
  • Sets Shell.LastErrorMessage on error (returns false).

  Example:

  var finished = varRecord.FinishTransition( transId, "True" );

  Example:

  var finished = varRecord.FinishTransition( transId, "True", "userName", "userPass" );

• QuickTransition( trans [, bool stealLock ] [, signedUserID, signedUserPwd ] ) (On-premise only): Identical to FinishTransition except StartTransition is not required. All field value changes must be in place on the item.

  Return: (bool)

  Example:

  var varRecord = Ext.CreateVarRecord( tableId );
  var read =  varRecord.Read( itemTitle );
  var finished = varRecord.QuickTransition( transitionId, "True", "userName", "userPass" );

• StartSubmitToAux() (On-premise only): Starts the submit of a new item into an auxiliary table.

  Return: (bool)

  Note the following:

  • StartSubmitToAux is not required, script can simply invoke QuickSubmitToAux if all required field values have already been set on the item. StartSubmitToAux will initialize fields as if the transition form has been opened on the end user interface. Fields will resond correctly to GetRequiredFlag.
  • Sets Shell.LastErrorMessage on error (returns false).

  Example:

  var varRecord = Ext.CreateVarRecord( auxTableId );
  var start = varRecord.StartSubmitToAux();
  

• FinishSubmitToAux() (On-premise only): Finishes the submit into an auxiliary table.

  Return: (bool)

  Note the following:

  • StartSubmitToAux should have been invoked. See notes on StartSubmitToAux.
  • Sets Shell.LastErrorMessage on error (returns false).

  Example:

  var submitted = varRecord.FinishSubmitToAux();

• QuickSubmitToAux() (On-premise only): Identical to FinishSubmitToAux except StartSubmitToAux is not required. All field value changes must be in place on the item.

  Return: (bool)

  Example:

  var varRecord = Ext.CreateVarRecord( auxTableId );
  varRecord.SetFieldValue( "title" , "my title" );
  var submit = varRecord.QuickSubmitToAux();