Getting Started

This tutorial will get you up and running quickly with the Sage Intacct SDK for .NET.

Make sure you meet the system requirements before continuing.

Set up

  1. Download and install .NET Core if you do not already have it installed.

  2. Download or clone the Sage Intacct SDK for .NET examples.

  3. Open the intacct-sdk-net-examples.sln solution file in your IDE of choice (Rider, Visual Studio 2017, etc.). This will display one project, Intacct.Examples, which is a .NET Core console application.

    For Visual Studio, you need to choose .NET Core cross-platform development. For Rider, .NET Core is the default.

  4. Open the Intacct.Examples folder in the file system and note that the Intacct.Examples.csproj file specifies the Sage Intacct SDK for .NET (Intacct.SDK) as a dependency.

  5. Depending on your IDE, you might need to install any referenced packages. For example, with Visual Studio community, right click on the Solution file and choose Restore NuGet Packages.

    This downloads the Sage Intacct SDK for .NET libraries and dependencies.

  6. Create a credentials.ini file in the Intacct.Examples project folder and provide your developer/sandbox credentials as follows:

    [default]
sender_id = "mysenderid"
sender_password = "mysenderpassword"
company_id = "mycompanyid"
user_id = "myuserid"
user_password = "myuserpassword"

    The default profile is automatically used unless overridden in the ClientConfig or by environment variables.

    The credentials file is excluded from source control via the .gitignore file. You should take precautions to secure this file.

  7. In your IDE, set the file properties on credentials.ini so that it will be copied into the output directory.

    Both Visual Studio and Ryder have a file property named Copy to output directory that you can set to Copy always or Copy if newer.

Understand the code

  1. Take a look at Bootstrap.cs in the project root and note that it:

    • Has a static Logger() function for creating an NLog logger.

      public static class Bootstrap
{

    public static ILogger Logger(string loggerName)
    {
       ILogger logger = (new NLogLoggerFactory()).CreateLogger(loggerName);

       return logger;
    }

    • Has a static Client() function for setting up a client config that relies on your credentials file and returns a new online client that uses the client config:

      public static OnlineClient Client(ILogger logger)
{
    ClientConfig clientConfig = new ClientConfig()
    {
        ProfileFile = Path.Combine(Directory.GetCurrentDirectory(), "credentials.ini"),
        Logger = logger,
    };
    OnlineClient client = new OnlineClient(clientConfig);
         
    return client;
}

  2. Open nlog.config in the project root and note that it sets up the log file as ${basedir}/logs/intacct.log and specifies Debug level logging. Accordingly, logging messages are written to Intacct.Examples/bin/Debug/netcoreappX.X/logs/intacct.log.

    ...
<targets>
    <!-- write logs to file -->
    <target xsi:type="File" name="logfile" fileName="${basedir}/logs/intacct.log"
    layout="${longdate}|${level}|${message} |${all-event-properties} ${exception:format=tostring}" />
</targets>  
<!-- rules to map from logger name to target -->
<rules>
    <logger name="*" minlevel="Debug" writeTo="logfile" />
</rules>

  3. Open Program.cs and note that it is the Main() function for your console application. This program wraps the examples and lets you choose one or more examples to run.

  4. Open GettingStarted.cs and note that it:

    • Constructs a Read instance that queries for customers:

       Read read = new Read()
 {
    ObjectName = "CUSTOMER",
    Fields = {
        "RECORDNO",
        "CUSTOMERID",
        "NAME",
    },
    Keys = {
        33
    }
 };

    • Executes the query using the online client instance (client) that was instantiated in the bootstrap file:

      Task<OnlineResponse> task = client.Execute(read);
task.Wait();
      
OnlineResponse response = task.Result;
Result result = response.Results[0];
dynamic json = JsonConvert.DeserializeObject(JsonConvert.SerializeObject(result.Data));

...
Console.WriteLine("Success! Found these customers: " + json);

Run the example

  1. Build and run the project, either from your IDE or the command line. For example, from the command line:

    cd Intacct.Examples

    "C:\Program Files\dotnet\dotnet.exe" build Intacct.Examples.csproj

     "C:\Program Files\dotnet\dotnet.exe" bin/Debug/netcoreappX.X/Intacct.Examples.dll

    The console menu appears:

     Available examples:
 1 - Getting started
 2 - List AR invoices
 3 - List vendors (legacy)
 4 - CRUD customer
 5 - Custom object function
 6 - Exit program

  2. Type 1 to choose the example and press enter.

  3. Observe the output, for example:

    Success! Found these customers: [
  {
    "CUSTOMER": {
      "RECORDNO": "131",
      "CUSTOMERID": "10125",
      "NAME": "Betty Smith"
    }
  }
]

  4. If you don’t get a result, replace the record number with ones that can be found in your company, for example:

    Keys = {
    12,10,44
}

  5. Open the generated log file, for example, Intacct.Examples\bin\Debug\netcoreappX.X\logs\intacct.log, and examine the entries.

    The SDK provided one DEBUG entry for the HTTP request with the Sage Intacct endpoint (/ia/xml/xmlgw.phtml HTTP/1.1), and another for the single response. The response includes the request control ID, which defaults to the timestamp of the request, and the function control ID, which defaults to a random UUID.

Extra credit

Log level and format

  1. Edit the public static Client function in the Bootstrap class to change the SDK’s log message format and log level.

  2. Add a using statement for Intacct.SDK.Logging:

    using Intacct.SDK.Logging;

  3. Add LogLevel and LogMessageFormatter property setters so that the Client now looks like this:

    public static OnlineClient Client(ILogger logger)
{
   ClientConfig clientConfig = new ClientConfig()
   {
       ProfileFile = Path.Combine(Directory.GetCurrentDirectory(), "credentials.ini"),
       Logger = logger,
       LogLevel = LogLevel.Information,
       LogMessageFormatter = new MessageFormatter("\"{method} {target} HTTP/{version}\" {code}"), 
   };
   OnlineClient client = new OnlineClient(clientConfig);
       
   return client;
}

  4. Build/run the project again, then open logs/intacct.log and review the new entries at the bottom. Note the response code is listed after the HTTP method in the info message that posts to the XML gateway:

    2020-11-10 09:52:09.7693|Info|"POST https://api.intacct.com/ia/xml/xmlgw.phtml HTTP/2.0" OK |

What’s next?

Provide feedback