Skip to main content
Indiana Wesleyan University Support Knowledge Base

Execute Envision Subroutines

  1. Last updated
  2. Save as PDF

Overview

Lists available options and methods for executing Colleague subroutines using ExportManager.

Details

Setup

The username and password with which to log in to Envision must be set in the ExportManager.config file for each instance (dev, test, live).  Consequently, you should not have to worry about this aspect of executing Envision subroutines.  The following setup & options are available:

ColleagueConnection.DatabaseName

String containing the SQL database name of the current Colleague account

ColleagueConnection.Account

Enumeration containing the name of each account: LIVE, TEST, DEV, ARCHIVE, SANDBOX, or NONE

ColleagueConnection.UserName

String containing the username used to log in to Colleague

ColleagueConnection.FM .VM .SM

Strings containing the traditional Unidata File Mark, Value Mark, and Sub-value Mark characters.

ColleagueConnection.HoldDirectory

This string will contain the path to the HOLD directory for the current account.  Use it to form the list of file names described below.

Execution

The following methods are available:

ColleagueConnection.LoginTest()

This method returns true or false indicating whether it was able to successfully connect to and log in to Colleague.

CallColleagueProcess()

There is only one method for calling Envision subroutines:  CallColleagueProcess( string, List<FileInfo>, object ).  When this method is executed, ExportManager will log into Colleague and execute a Colleague Transaction named EXECUTE.HOOK.I35.

This Colleague Transaction will log the information you sent to EXECUTE.HOOK.I35.LOG in the PH directory, and then call the subroutine you named, passing it the file list converted to multi-value list as the first argument, and the parsed object data you sent as a string or multi-value array as appropriate.  If you're curious how this works, the Transaction can be imported into Colleague Studio.

string processName
The first argument is the name of the subroutine to call.
ref List<FileInfo> fileNames
The second argument is a List template type of FileInfo objects. These should be local path references to file names within the HOLD directory.  See example below.  Use this argument to pass the desired output file names into or out of the Envision subroutine.
ref object data
The final argument can be any string or value type or list thereof.  If the object is a list or other enumerable type, it will be parsed out into a Unibasic multi-value array up to the sub-value level.  Use this argument to pass data to and from the Envision subroutine.
/// <summary>
/// Execute an Envision process
/// </summary>
/// <param name="processName">Name of the Envision process to execute</param>
/// <param name="fileNames">Name of the file in _HOLD_ used or generated</param>
/// <param name="data">Envision formatted data passed to/from process</param>
public virtual void CallColleagueProcess( string processName, ref List<FileInfo> fileNames, ref object data )

CallColleagueProcessAsync()

 This method performs the same action with the same parameters but in an asynchronous context.  The primary difference is that instead of passing arguments by reference (not allowed asynchronously), the await CallColleagueProcessAsync() command will return a struct of type ColleagueProcessArguments which contains the two properties  FileNames and Data.

This allows you to launch a Colleague subroutine and then perform other operations such as LoadFromDB() and WriteToDisk() while you wait for it to complete.  See AsyncSample.cs for an example.

/// <summary>
/// Execute an Envision process
/// </summary>
/// <param name="processName">Name of the Envision process to execute</param>
/// <param name="fileNames">Name of the file in _HOLD_ used or generated (Note this is NOT a reference parameter. Use the ColleagueProcessArguments object returned.)</param>
/// <param name="data">Envision formatted data passed to/from process (Note this is NOT a reference parameter. Use the ColleagueProcessArguments object returned.)</param>
public async Task<ColleagueProcessArguments> CallColleagueProcessAsync( string processName, List<FileInfo> fileNames, object data )

Example

Script

The example below will test its ability to log in to Colleague and call the subroutine if successful.

// Get data from Colleague
object data   = "DATA-TO-USE";
var fileNames = new List<FileInfo>();
fileNames.Add( new FileInfo( Path.Combine( ColleagueConnection.HoldDirectory, "SampleExportColleagueData.csv" ) ) );

if ( Colleague.Login() )
{
    CallColleagueProcess( "S.HELLO.WORLD.I35", ref fileNames, ref data );
    // Move the resulting files from HOLD into the root of the working set for this export
    // and delete them out of HOLD.
    ImportFiles( null, true, fileNames );
}

Log output

Expected ExportManager log output:

2016-09-13 15:57:13.8114 INFO -------------------------------------------------------------------------------
2016-09-13 15:57:13.8794 INFO IWU Export Manager launched
2016-09-13 15:57:13.8914 INFO -------------------------------------------------------------------------------
2016-09-13 15:57:13.8914 TRACE OS=Microsoft Windows NT 6.1.7601 Service Pack 1  Cores=4  64bit=True
    Machine=IWU71563  Domain=IWUNET  User=konrad.willmert
    Command=ExportManager  ColleagueSample
-------------------------------------------------------------------------------
2016-09-13 15:57:13.9504 DEBUG Export "AccuTrack" found
2016-09-13 15:57:13.9704 DEBUG Export "BasicSample" found
2016-09-13 15:57:13.9874 DEBUG Export "ColleagueSample" found
2016-09-13 15:57:14.0014 DEBUG Export "ColleagueTest" found
2016-09-13 15:57:14.0014 DEBUG Export "SampleExport" found
2016-09-13 15:57:14.5184 INFO Executing "ColleagueSample"
2016-09-13 15:57:17.0804 DEBUG "ColleagueSample" export process executed in 3,044ms
2016-09-13 15:57:17.0964 DEBUG IWU.ExportManager.Exports.ColleagueSample FileManager@C:\Users\konrad.willmert\Source\Repos\IWUExportManager\IWUExportManager\bin\Release\data\ColleagueSample: 0 data files, 1 other files, other files imported ColleagueConnection mocha.task@DEV with database "coll18_dev" and HOLD dir "\\ERPapp\d$\datatel\ftp\coll18_dev\data\_HOLD_"
2016-09-13 15:57:17.1104 DEBUG ExportManager total run time: 3,300ms
2016-09-13 15:57:17.1234 INFO Exiting.

Expected export log output:

2016-09-13 15:57:14.5634 INFO -------------------------------------------------------------------------------
2016-09-13 15:57:14.5634 INFO IWU.ExportManager.Exports.ColleagueSample initializing.
2016-09-13 15:57:14.5634 INFO -------------------------------------------------------------------------------
2016-09-13 15:57:15.4884 WARN TEST MODE is enabled. No actual data files will be exported/uploaded. Instead, write access will be tested. Override with "notest".
2016-09-13 15:57:15.5134 DEBUG Data directory: C:\Users\konrad.willmert\Source\Repos\IWUExportManager\IWUExportManager\bin\Release\data\ColleagueSample
2016-09-13 15:57:15.5354 DEBUG Archive directory: C:\Users\konrad.willmert\Source\Repos\IWUExportManager\IWUExportManager\bin\Release\archive\ColleagueSample
2016-09-13 15:57:16.5754 DEBUG ColleagueConnection mocha.task@DEV with database "coll18_dev" and HOLD dir "\\ERPapp\d$\datatel\ftp\coll18_dev\data\_HOLD_"
2016-09-13 15:57:16.5754 INFO Executing Colleague process "S.HELLO.WORLD.I35" on DEV account
2016-09-13 15:57:16.7714 DEBUG Successfully logged in to Colleague DEV as "mocha.task"
2016-09-13 15:57:16.9844 DEBUG Successfully executed Colleague process "S.HELLO.WORLD.I35" in 392ms.
2016-09-13 15:57:16.9844 DEBUG HookResponse Response type: Value FileName: SampleExportColleagueData.csv Data: DATA-TO-USE
2016-09-13 15:57:17.0074 INFO Importing file(s) into working set.
2016-09-13 15:57:17.0484 DEBUG Copied "\\ERPapp\d$\datatel\ftp\coll18_dev\data\_HOLD_\SampleExportColleagueData.csv" to "C:\Users\konrad.willmert\Source\Repos\IWUExportManager\IWUExportManager\bin\Release\data\ColleagueSample\SampleExportColleagueData.csv"
2016-09-13 15:57:17.0634 INFO Successfully copied 1 file(s).
2016-09-13 15:57:17.0634 DEBUG Successfully copied 46 bytes in 1 file(s) in 41ms

Results

The List<FileInfo> and object arguments are reference arguments and could potentially be modified by the Envision subroutine and returned.  You can then use these in your export script as the example does.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Reference
    Stage
    Final
  2. Tags
    This page has no tags.