CAA Web Services Home

 

Consuming the ENOVWSLCMgmtCpp CAA Web Service

Using the ENOVWSLCMgmtCpp CAA Web service for lifecycle management
Use Case

Abstract

This article discusses the CAAENOVWSDotNet1_1Client use case. It describes how to use the C# client binding that can be generated using the wsdl.exe utility in order to consume the ENOVWSLCMgmtCpp CAA Web service. It provides a sample usage scenario that demonstrates how to handle lifecycle management.

What You Will Learn With This Use Case

This use case demonstrates how to write a client application that consumes the ENOVWSProdStructCpp CAA Web service. It helps you to:

[Top]

The CAAENOVWSDotNet1_1Client Use Case

CAAENOVWSDotNet1_1Client is a use case of the CAAENOVWS.edu framework that illustrates the ENOVWSLCMgmtCpp CAA Web service capabilities.

[Top]

What Does CAAENOVWSDotNet1_1Client Do

The sample usage scenario delivered with this use case contains the following steps:

The ENOVWSLCMgmtCpp CAA Web service is used in support of the primary objective of this use case, which is to get and apply transitions using the ENOVWSLCMgmtCpp CAA Web service.

[Top]

Where To Find the CAAENOVWSDotNet1_1Client Code

The CAAENOVWSDotNet1_1Client use case is made of several classes located in both CAAENOVWSDotNet1_1Client.m and CAAENOVWSDotNet1_1ClientBase.m modules of the CAAENOVWS.edu framework:

<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1Client.m\src
<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1ClientBase.m\src

The CAAENOVWSDotNet1_1ClientBase.m module (library) contains the following resources:

<Source>\CAAENOVWSLCMgmtCppProxy.cs
<Source>\CAAENOVWSLCMgmtCppWrapper.cs
<Source>\CAAENOVWSUtils.cs

The CAAENOVWSLCMgmtCppProxy.cs file contains the C# client binding generated using the wsdl.exe utility. A C# client binding consists of a proxy and several types definitions. The CAAENOVWSLCMgmtCppWrapper.cs file contains a class that describes how to configure the generated proxy and how to invoke its methods.

The CAAENOVWSDotNet1_1Client.m module (executable) contains the following resources:

<Source>\CAAENOVWSDotNet1_1Client.cs
<Source>\CAAENOVWSLCMgmtCppUseCase.cs

The CAAENOVWSDotNet1_1Client.cs file contains the main program. It parses the command line inputs and starts up the use case. The CAAENOVWSLCMgmtCppUseCase.cs file contains the sample use case scenario.

[Top]

How to Launch CAAENOVWSDotNet1_1Client

To run the CAAENOVWSDotNet1_1Client use case, you will need to build both CAAENOVWSDotNet1_1ClientBase.m and CAAENOVWSDotNet1_1Client.m modules. The use case code can be built using either the CAA V5 buildtime environment, or Visual Studio .NET 2003 as explained in [1].

You can then execute the command described below:

CAAENOVWSDotNet1_1Client -w <URI> -e <ENOVIA username> -u <Basic Authentication username> -p <Basic Authentication password> -t ENOVWSLCMgmtCpp

Here follows a sample command, to be updated with your own environment configuration:

CAAENOVWSDotNet1_1Client -w http://stophe1dsy.dsy.ds:9080/B17 -e cjk -u wpsadmin -p wpsadmin -t ENOVWSLCMgmtCpp

The same executable is used to launch all of the available ENOVIA CAA Web services use cases. The -t option is used to choose the target use case to run.

When building the modules with the CAA V5 buildtime environment, the CAAENOVWSDotNet1_1Client executable can be launched from the following location:

<Install>\CAAENOVWS.edu\intel_a\code\clr

[Top]

Step-by-step

The following section first explains how to generate the C# client binding for the ENOVWSLCMgmtCpp CAA Web service demonstrated. The remaining sections describe how to configure the generated proxy and how to consume the Web service:

  1. Creating the C# Client Binding
  2. Instantiating and Configuring the Generated Proxy
  3. Getting Transitions
  4. Applying Transitions
  5. Sample Usage Scenario

[Top]

Creating the C# Client Binding

Please refer to [2] for details on how to generate the C# client binding using the wsdl.exe utility.

Here follows a sample command in order to generate the C# client binding for the ENOVWSLCMgmtCpp CAA Web service:

wsdl /namespace:com.dassault_systemes.caaenovws.caaenovwsdotnet1_1clientgen.enovwslcmgmtcpp /username:wpsadmin /password:wpsadmin /out:CAAENOVWSLCMgmtCppProxy.cs http://stophe1dsy.dsy.ds:9080/B17/wsdl?service=urn:com:dassault_systemes:ENOVWSLCMgmtImpl:ENOVWSLCMgmtImpl:ENOVWSLCMgmtCpp

The server name, port, and context root URI information must be updated to match the server where the ENOVWSLCMgmtCpp CAA Web service has been deployed. The /username and /username options are required to authenticate on the Web server hosting the Web service.

[Top]

Instantiating and Configuring the Generated Proxy

In order to consume an implementation of the ENOVWSLCMgmtCpp CAA Web service deployed on a target Web server, you first need to instantiate the proxy generated using the wsdl.exe utility. This proxy must then be configured in order to manage authentication on the remote Web server, timeout, and session management. Maintaining the HTTP session state is mandatory when consuming ENOVIA LCA V5 CAA Web services.

The generated proxy class is used in order to marshall method calls and objects to SOAP requests, and to unmarshall SOAP responses to objects. The following code describes how to instantiate and configure it:

public class CAAENOVWSLCMgmtCppWrapper {
  private const string SERVICE_ID = "urn:com:dassault_systemes:ENOVWSLCMgmtImpl:ENOVWSLCMgmtImpl:ENOVWSLCMgmtCpp";
  private CAAENOVWSLCMgmtCppProxy proxy = null;

  public CAAENOVWSLCMgmtCppWrapper(
    CookieContainer container,
    string uri,
    string credUser,
    string credPwd,
    int timeOut) {
    proxy = new CAAENOVWSLCMgmtCppProxy();

    // Compute the SOAP endpoint URI value that bounds to the deployed
    // implementation of the ENOVWSLCMgmtCpp CAA Web service
    proxy.Url = uri + "servicerouter?service=" + SERVICE_ID;

    // Required for HTTP session state management
    proxy.CookieContainer = container; (1)

    // Required for the Basic Authentication mechanism
    ICredentials credentials = new NetworkCredential(credUser, credPwd);
    proxy.Credentials = credentials; (2)

    // Increase the default client time-out
    proxy.Timeout = timeOut; (3)
  }
}

(1): in order to maintain the HTTP session state between successive calls performed using either the same or multiple proxy instances, the CookieContainer property must be set on the proxy. This is mandatory in the context of ENOVIA LCA V5 CAA Web services,
(2): when security is enabled on the remote Web server, it is mandatory to set the Credentials property on the proxy. The values specified must match a valid set of credentials for the Basic Authentication mechanism,
(3): the default timeout value can be increased in order to avoid potential issues at runtime, such as losing the HTTP connection before receiving the SOAP responses. The value specified in the code is in milliseconds.

[Top]

Getting Transitions

To get a list of lifecycle transition names, you can use the following method available through the generated proxy interface:

public Status GetTransitions(Identifier iObjectId, ref string[] oTransitionNames)

This method accepts the following parameters:

[in] iObjectId   The identifier of the target object
[in/out] oTransitionNames   The list of transition names which are available to apply

The following code demonstrates the use of the GetTransitions method:

public class CAAENOVWSLCMgmtCppWrapper {
  ...
  private Identifier ToIdentifier(string id) {
    if (id == null) {
      throw new ApplicationException("Illegal argument: identifier value is null");
    }

    Identifier identifier = new Identifier();
    identifier.Identifier1 = CAAENOVWSUtils.ConvertFromHexToBinary(id);
    return identifier;
  }

  public string[] GetTransitions(string objectUUID) {
    if (objectUUID == null) {
      throw new ApplicationException("Illegal argument: object UUID is null");
    }

    Identifier objectId = ToIdentifier(objectUUID);
    string[] transitionNames = null;

    try {
      Status status = proxy.GetTransitions(objectId, ref transitionNames);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to get transitions", e);
    }

    if (transitionNames == null) {
      throw new ApplicationException("Failed to get transitions");
    }
    return transitionNames;
  }
}

The CAAENOVWSUtils.ConvertFromHexToBinary method can be found at:

<Source>\CAAENOVWSUtils.cs

[Top]

Applying Transitions

To apply a lifecycle transition, you can use the following method available through the generated proxy interface:

public Status ApplyTransition(Identifier iObjectId, string iTransitionName)

This method accepts the following parameters:

[in] iObjectId   The identifier of the target object
[in] iTransitionName   The name of the transition to apply

The following code demonstrates the use of the ApplyTransition method:

public class CAAENOVWSLCMgmtCppWrapper {
  ...
  public void ApplyTransition(string objectUUID, string transitionName) {
    if (objectUUID == null) {
      throw new ApplicationException("Illegal argument: object UUID is null");
    } else if (transitionName == null) {
      throw new ApplicationException("Illegal argument: transition name is null");
    }

    Identifier objectId = ToIdentifier(objectUUID);

    try {
      Status status = proxy.ApplyTransition(objectId, transitionName);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to apply transitions", e);
    }
  }
}

[Top]

Sample Usage Scenario

The following code depends on:

It demonstrates a sample usage scenario for the ENOVWSLCMgmtCpp CAA Web service:

public class CAAENOVWSLCMgmtCppUseCase {
  private string uri = null;
  private string credUser = null;
  private string credPwd = null;

  public CAAENOVWSLCMgmtCppUseCase(
    string uri,
    string credUser,
    string credPwd) {
    this.uri = uri;
    this.credUser = credUser;
    this.credPwd = credPwd;
  }

  public void RunSampleUsageScenario(string enoviaUser) {
    enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper binderWrapper = null;
    enoposapplicationbinderimpl.SessionToken sessionToken = null;
    try {
      // ------------------------------------------------------------
      // Step 1 - Instantiate and configure the proxies
      // ------------------------------------------------------------

      // Create a CookieContainer object to maintain the HTTP session 
      // state accross proxies
      CookieContainer container = new CookieContainer();

      // Instantiate wrapper client classes
      int timeOut = 360000;
      binderWrapper =
        new enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper(
          container, uri, credUser, credPwd, timeOut);
      enovwsprodstructcpp.CAAENOVWSProdStructCppWrapper prodStructWrapper =
        new enovwsprodstructcpp.CAAENOVWSProdStructCppWrapper(
          container, uri, credUser, credPwd, timeOut);
      enovwslcmgmtcpp.CAAENOVWSLCMgmtCppWrapper lcMgmtWrapper =
        new enovwslcmgmtcpp.CAAENOVWSLCMgmtCppWrapper(
          container, uri, credUser, credPwd, timeOut);

      // ------------------------------------------------------------
      // Step 2 - Open session with ENOVIA LCA V5
      // ------------------------------------------------------------

      // Get user contexts
       string[] userContexts = binderWrapper.GetUserContexts(enoviaUser);

      // Log in using the first available context
      if (userContexts.Length == 0) {
        throw new ApplicationException("No context found for the user specified");
      }
      sessionToken = binderWrapper.Login(userContexts[0]);

      // ------------------------------------------------------------
      // Step 3 - Create a part reference to test with
      // ------------------------------------------------------------

      enovwsprodstructcpp.ENOVIA createPartResultSet =
        prodStructWrapper.CreatePartRef(
          new string[] { "ILCMgmtWS_CAA_PartRef1" }, "", "FALSE");

      string[] partRefUUIDs =
        prodStructWrapper.GetENOVIA_VPMPartVersionUUIDs(createPartResultSet);
      if (partRefUUIDs.Length > 1) {
        throw new ApplicationException("Invalid state: more than 1 part reference was returned");
      } else if (partRefUUIDs.Length != 1) {
        throw new ApplicationException("Failed to create part reference");
      }
      string partRefUUID = partRefUUIDs[0];

      // ------------------------------------------------------------
      // Step 4 - Get 'Promote' transition
      // ------------------------------------------------------------

      string[] transitionNames = lcMgmtWrapper.GetTransitions(partRefUUID);

      for (int i = 0; i < transitionNames.Length; i++) {
        Console.Out.WriteLine("Transition[{0}]={1}", i, transitionNames[i]);
      }

      // ------------------------------------------------------------
      // Step 5 - Apply default transition
      // ------------------------------------------------------------

      // As we just created the part, there should only be 1 transition, 'Promote'
      if (transitionNames.Length == 0) {
        throw new ApplicationException("Failed to get default transition");
      } else if (transitionNames.Length != 1 || !"Promote".Equals(transitionNames[0])) {
        throw new ApplicationException("Use case does not handle customized lifecycle");
      }

      lcMgmtWrapper.ApplyTransition(partRefUUID, transitionNames[0]);

      // ------------------------------------------------------------
      // Step 6 - Get transitions
      // ------------------------------------------------------------

      transitionNames = lcMgmtWrapper.GetTransitions(partRefUUID);

      for (int i = 0; i < transitionNames.Length; i++) {
        Console.Out.WriteLine("Transition[{0}]={1}", i, transitionNames[i]);
      }

      // ------------------------------------------------------------
      // Step 7 - Apply 'Demote' transition
      // ------------------------------------------------------------

      // As we promoted the part, there should now only be 2 transitions, 'Promote' & 'Demote'
      if (transitionNames.Length == 0) {
        throw new ApplicationException("Failed to get default transition");
      } else if (transitionNames.Length != 2 || !"Promote".Equals(transitionNames[0]) || !"Demote".Equals(transitionNames[1])) {
        throw new ApplicationException("Use case does not handle customized lifecycle");
      }

      // Apply 'Demote' transition
      lcMgmtWrapper.ApplyTransition(partRefUUID, transitionNames[1]);

      // ------------------------------------------------------------
      // Step 8 - Get default transition again
      // ------------------------------------------------------------

      transitionNames = lcMgmtWrapper.GetTransitions(partRefUUID);

      // As we demoted the part, we should be back to the same start state
       for (int i = 0; i < transitionNames.Length; i++) {
        Console.Out.WriteLine("Transition[{0}]={1}", i, transitionNames[i]);
      }

      if (transitionNames.Length != 1 || !"Promote".Equals(transitionNames[0])) {
        throw new ApplicationException("Failed to return to initial state");
      }

      // ------------------------------------------------------------
      // Step 9 - Cleanup by deleting created part reference
      // ------------------------------------------------------------

      prodStructWrapper.DeletePartRef(new string[] { partRefUUID });
     } catch (Exception e) {
      ...
    } finally {
      // ------------------------------------------------------------
      // Step 10 - Terminate opened session
      // ------------------------------------------------------------

      // The session must be closed even if a call to a method on the ENOVWSQueryCpp
      // CAA Web service fails
      binderWrapper.Logout(sessionToken);
     }
  }
}

[Top]

In Short

This use case explains how to use the C# client binding generated using the wsdl.exe utility in order to consume the ENOVWSLCMgmtCpp CAA Web service. It also gives an overview of the available methods:

[Top]

References

[1] Building and Launching a CAA Web Service Use Case
[2] Generating a C# Client Binding
[3] Consuming the ENOPosApplicationBinderImpl CAA Web Service
[4] Consuming the ENOVWSProdStructCpp CAA Web Service
[Top]

History

Version: 1 [Jan 2006] Document created
[Top]

Copyright © 2006, Dassault Systèmes. All rights reserved.