Analytica Docs - User contributions [en]

Salesforce REST library

2026-09-30T19:26:51Z

Lchrisman: Document SFLogin(): interactive browser sign-in

[[Category:Function libraries]]
[[Category:Integration Functions]]

{{ReleaseBar}}

''Requires [[Analytica 7.1]] {{Analytica Developer}} edition or better.''

The '''Salesforce REST library''' lets your model authenticate with [https://www.salesforce.com/ Salesforce] and read Salesforce records and metadata through the Salesforce REST API, version 67.0. Use it to pull live data -- accounts, contacts, opportunities, or your own custom objects -- straight into an Analytica model, so that your analysis works from current CRM data instead of an exported snapshot.

It provides:
* Interactive sign-in through your web browser, as yourself, for desktop use
* OAuth 2.0 client-credentials authentication for unattended, server-to-server use
* A legacy SOAP-login option as a temporary migration bridge
* SOQL query execution, including automatic pagination
* Record-selection and record-retrieval helpers
* Salesforce object and field metadata
* SOSL search

This library reads from Salesforce. It has no functions to create, update, or delete Salesforce records.

'''Download:''' [[media:Salesforce REST library.ana|Salesforce REST library.ana]] (v. 1.02)

== Requirements ==

To use this library, you need:
* [[Analytica 7.1]] or later, {{Analytica Developer}} edition or better. The library is built on [[ReadFromUrl]](), which is not available in the Professional or Player editions.
* A Salesforce account. [[#SFLogin|SFLogin]]() needs nothing more. [[#ClientCredentialsAuth|ClientCredentialsAuth]]() also needs an OAuth client configured in Salesforce (see [[#Setting up Salesforce for client-credentials authentication|Setting up Salesforce]] below).
* Internet access allowing Analytica to reach your Salesforce login and instance domains over HTTPS. If you have a strong firewall, you may need to add a rule to allow this.

== Getting started ==

# [[media:Salesforce REST library.ana|Download the library]] and save it into your <code>"C:\Program Files\Lumina\Analytica 7.1\Libraries"</code> folder.
# Launch Analytica and open your model, or start a new one.
# Select '''Add Library...''' from the '''File''' menu, select <code>Salesforce REST library.ana</code>, click '''OK''', select '''Link''', then click '''OK'''.

The simplest way to connect is to sign in as yourself. [[#SFLogin|SFLogin]]() opens your web browser at the Salesforce login page and returns the connection when you've signed in:

<pre style="background:white; border:white; margin-left: 1em;">
Variable Sf ::= SFLogin()

Variable Active_accounts ::= SalesforceSelect( Sf, "Account", "Id, Name, Industry",
where: "IsDeleted = false",
order_by: "Name",
row_limit: 100 )
</pre>

For unattended use, such as a model that runs on a server, authenticate with client credentials instead. A model then uses three Variables -- an authentication Struct, a connection Struct, and one or more query results:

<pre style="background:white; border:white; margin-left: 1em;">
Variable Sf_auth ::= ClientCredentialsAuth(
"https://login.salesforce.com",
Sf_client_id,
Sf_client_secret )

Variable Sf ::= Salesforce( Sf_auth )

Variable Active_accounts ::= SalesforceSelect( Sf, "Account", "Id, Name, Industry",
where: "IsDeleted = false",
order_by: "Name",
row_limit: 100 )
</pre>

<code>Active_accounts</code> is a query-result [[Struct]]. Its list of records is:
:<code>Active_accounts -> records</code>

To read a field from the first record:
:<code>SalesforceField( Active_accounts -> records[@=1], "Name" )</code>

When you authenticate to a sandbox, use <code>"https://test.salesforce.com"</code> in place of <code>"https://login.salesforce.com"</code>.

== A brief introduction to SOQL ==

Salesforce Object Query Language (SOQL) resembles SQL, but it queries Salesforce objects and fields by their '''API names''' rather than by table and column names. A basic query looks like this:

<pre style="background:white; border:white; margin-left: 1em;">
SELECT Id, Name, Industry
FROM Account
WHERE Industry = 'Technology'
ORDER BY Name
LIMIT 100
</pre>

Standard object names include <code>Account</code>, <code>Contact</code>, and <code>Opportunity</code>. API names of custom objects and custom fields usually end in <code>__c</code> -- for example <code>License__c</code> or <code>Expiration_Date__c</code>. An object's API name is often not the same as the label you see in the Salesforce user interface, so use [[#SalesforceObjects|SalesforceObjects]]() and [[#SalesforceFields|SalesforceFields]]() to discover the names you need.

Whenever you insert a text value into a SOQL expression, quote it with [[#SalesforceSoqlQuote|SalesforceSoqlQuote]](). Don't use that function for object or field API names.

For the full language, see the Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference].

== Setting up Salesforce for client-credentials authentication ==

[[#ClientCredentialsAuth|ClientCredentialsAuth]]() is meant for unattended, server-to-server access. It needs an OAuth client configured in Salesforce, plus a dedicated Salesforce user whose permissions the integration runs under.

Salesforce terminology and Setup screens vary by edition and release. In current releases the OAuth client is normally an '''External Client App'''; some organizations still use a '''Connected App'''.

A Salesforce administrator generally needs to:
# Create an '''External Client App''' in Salesforce Setup.
# Enable '''OAuth settings''' and the '''OAuth 2.0 Client Credentials Flow'''.
# Grant the OAuth scope needed for REST access, normally '''Manage user data via APIs''' (<code>api</code>). Avoid broader scopes unless you need them.
# Save the app, then copy its '''Consumer Key''' and '''Consumer Secret'''. These become the «client_id» and «client_secret» parameters in Analytica.
# In the app's OAuth policies, select a dedicated '''Run As''' integration user for the client-credentials flow. Depending on the app type, Salesforce may also require '''Admin approved users are pre-authorized'''.
# Give the integration user the permissions your model needs -- API access, plus read access to the required objects and fields. Prefer permission sets and least privilege.
# If the app uses pre-authorization, assign the app's permission set or profile authorization to the integration user.

The library sends the token request to:
:<code>https://login.salesforce.com/services/oauth2/token</code>
or, for a sandbox:
:<code>https://test.salesforce.com/services/oauth2/token</code>

Salesforce returns an access token and the instance URL that the library uses for all later requests.

For current Salesforce-side details, see the Salesforce [https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-client-credentials-flow.html OAuth 2.0 Client Credentials Flow] documentation.

=== Protect the client secret ===

The consumer secret grants access as the configured integration user. Don't save it in a model that you distribute to people who shouldn't have the credential, and don't commit it to source control. Where you can, obtain it at deployment time from your organization's approved secret-management mechanism.

== Authentication and connection ==

The library offers three ways to authenticate:
* [[#SFLogin|SFLogin]]() -- you sign in through your browser as yourself. Best for interactive, desktop use.
* [[#ClientCredentialsAuth|ClientCredentialsAuth]]() -- unattended, server-to-server access as a dedicated integration user.
* [[#SoapLoginAuth|SoapLoginAuth]]() -- legacy username-and-password login, which stops working on 1-Jun-2027.

=== <span id="SFLogin">SFLogin()</span> ===

Signs you in to Salesforce interactively and returns a connection Struct, ready to pass to the query, record, search, and metadata functions.

When it evaluates, it opens your default web browser at the Salesforce login page. Sign in as usual -- including any multi-factor authentication your organization requires -- and, the first time, approve access for '''Desktop Analytica'''. The browser then says you may close the window, and the evaluation completes. Your model reads Salesforce with your own permissions: it sees the objects, fields, and records that you can see.

You don't need to set anything up in Salesforce, and there is no client ID or secret for you to supply or protect. It uses the OAuth 2.0 authorization-code flow with PKCE, through an external client app that Lumina registered with Salesforce. Your password goes only to Salesforce, never to Analytica or your model.

Example:
:<code>Variable Sf ::= SFLogin()</code>

The Struct it returns contains the same members as the one from [[#Salesforce|Salesforce]](), so you use it directly -- don't pass it to <code>Salesforce()</code>:
* <code>api_version</code> -- <code>"67.0"</code>
* <code>instance_url</code> -- your organization's instance, from Salesforce's user-information service
* <code>access_token</code>
* <code>rest_base_url</code>

Things to know:
* It signs in to production Salesforce, at <code>login.salesforce.com</code>. It doesn't support sandbox logins.
* During sign-in, Salesforce sends the result back to Analytica at <code>http://localhost:18756</code>. Port 18756 must be free on your computer, and your firewall must allow Analytica to listen on it for that local connection.
* It doesn't renew the access token. When your Salesforce session expires, requests fail with HTTP 401; recompute <code>SFLogin()</code> to sign in again.
* Because it needs a person at a browser, don't use it in a model that runs unattended. Use [[#ClientCredentialsAuth|ClientCredentialsAuth]]() for that.

[[Parameter types]]: <code>SFLogin()</code>

=== <span id="ClientCredentialsAuth">ClientCredentialsAuth(login_url, client_id, client_secret)</span> ===

Authenticates using the OAuth 2.0 client-credentials flow and returns a [[Struct]] holding the access token.

:{| class=wikitable
! Parameter
! Meaning
|-
| «login_url»
| <code>"https://login.salesforce.com"</code> for production, or <code>"https://test.salesforce.com"</code> for a sandbox
|-
| «client_id»
| Consumer key from the Salesforce External Client App or Connected App
|-
| «client_secret»
| Consumer secret from the same app
|}

The Struct it returns contains these members:
* <code>access_token</code>
* <code>instance_url</code>
* <code>status_code</code>
* <code>status_text</code>
* <code>raw_response</code>

Example:
:<code>ClientCredentialsAuth( "https://login.salesforce.com", Sf_client_id, Sf_client_secret )</code>

When authentication fails, it reports an Analytica error that includes the HTTP status and the Salesforce response.

[[Parameter types]]: <code>ClientCredentialsAuth(login_url: Text; client_id: Text; client_secret: Text)</code>

=== <span id="Salesforce">Salesforce(auth)</span> ===

Creates the connection Struct that you pass to every query, record, search, and metadata function. «auth» is the Struct returned by [[#ClientCredentialsAuth|ClientCredentialsAuth]]() or [[#SoapLoginAuth|SoapLoginAuth]](). You don't need this function with [[#SFLogin|SFLogin]](), which returns a connection itself.

The Struct it returns contains these members:
* <code>api_version</code> -- <code>"67.0"</code>
* <code>instance_url</code>
* <code>access_token</code>
* <code>rest_base_url</code>

Example:
:<code>Salesforce( Sf_auth )</code>

It's usually clearer to define the authentication and the connection as separate Variables, as shown in [[#Getting started|Getting started]], so that you can inspect an authentication failure on its own. You can also nest the calls:

<pre style="background:white; border:white; margin-left: 1em;">
Salesforce(
ClientCredentialsAuth(
"https://login.salesforce.com",
Sf_client_id,
Sf_client_secret ) )
</pre>

All REST calls use API version 67.0, including calls authenticated through [[#SoapLoginAuth|SoapLoginAuth]]().

[[Parameter types]]: <code>Salesforce(auth)</code>

=== <span id="SoapLoginAuth">SoapLoginAuth(login_url, username, password, security_token)</span> ===

Logs in with the legacy Salesforce SOAP Partner API <code>login()</code> call and returns a Struct whose session ID the REST functions use as a bearer token.

«security_token» is the Salesforce security token for that user account. The function concatenates it onto the password, as SOAP login requires.

'''This authentication method is a migration bridge only.''' Salesforce retires the SOAP <code>login()</code> mechanism on '''1-Jun-2027''', after which this function stops working. Write new models against [[#SFLogin|SFLogin]]() or [[#ClientCredentialsAuth|ClientCredentialsAuth]](), and migrate existing ones before that date.

[[Parameter types]]: <code>SoapLoginAuth(login_url: Text; username: Text; password: Text; security_token: Text)</code>

== Query functions ==

=== <span id="SalesforceSelect">SalesforceSelect(sf, sobject, fields, ''where, order_by, row_limit'')</span> ===

Builds and runs a common SOQL <code>SELECT</code>. This is the easiest entry point when your query has a straightforward <code>WHERE</code>, <code>ORDER BY</code>, and <code>LIMIT</code> structure. It returns the same query-result Struct as [[#SalesforceQuery|SalesforceQuery]]().

:{| class=wikitable
! Parameter
! Meaning
|-
| «sf»
| The connection returned by [[#Salesforce|Salesforce]]()
|-
| «sobject»
| Salesforce object API name, such as <code>"Account"</code>
|-
| «fields»
| Comma-separated field API names
|-
| «where»
| Optional SOQL condition, without the <code>WHERE</code> keyword
|-
| «order_by»
| Optional ordering expression, without the <code>ORDER BY</code> keywords
|-
| «row_limit»
| Optional maximum number of records. <code>0</code>, the default, applies no explicit limit
|}

The three optional parameters are declared <code>Named</code>, so pass them by name:

<pre style="background:white; border:white; margin-left: 1em;">
SalesforceSelect( Sf, "Contact", "Id, Name, Email, Account.Name",
where: "Email = " & SalesforceSoqlQuote( Target_email ),
order_by: "Name",
row_limit: 20 )
</pre>

It validates the object and field API names, but «where» and «order_by» are SOQL fragments that you supply. Quote any text value you interpolate into them with [[#SalesforceSoqlQuote|SalesforceSoqlQuote]](), as in the example above.

[[Parameter types]]: <code>SalesforceSelect(sf; sobject: Text; fields: Text; where: Named Text := ""; order_by: Named Text := ""; row_limit: Named Number := 0)</code>

=== <span id="SalesforceQuery">SalesforceQuery(sf, soql, ''include_deleted, max_pages'')</span> ===

Runs a complete SOQL expression and follows Salesforce pagination until it has retrieved every page.

It returns a query-result Struct with these members:

:{| class=wikitable
! Member
! Meaning
|-
| <code>records</code>
| List of parsed Salesforce record Structs
|-
| <code>total_size</code>
| Total matching records, as reported by Salesforce
|-
| <code>pages</code>
| Number of pages retrieved
|-
| <code>done</code>
| Whether Salesforce reported the query complete
|-
| <code>next_records_url</code>
| URL of a subsequent page. Normally <code>Null</code> once the query is complete
|-
| <code>raw_response</code>
| Raw response for the final page
|}

Set «include_deleted» to <code>True</code> to use Salesforce's query-all behavior, which can include deleted and archived records where Salesforce supports it.

«max_pages», 100 by default, protects your model from an unexpectedly large or insufficiently bounded query. If the result needs more pages than this, it raises an error rather than quietly returning an incomplete result.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
Local soql := "SELECT Id, Name, Amount, CloseDate " &
"FROM Opportunity " &
"WHERE IsClosed = false " &
"ORDER BY CloseDate";
SalesforceQuery( Sf, soql )
</pre>

[[Parameter types]]: <code>SalesforceQuery(sf; soql: Text; include_deleted := False; max_pages: Number := 100)</code>

=== <span id="SalesforceQueryFirst">SalesforceQueryFirst(sf, soql)</span> ===

Runs a SOQL expression and returns the first matching record Struct, or <code>Null</code> when nothing matches. Include an <code>ORDER BY</code> clause whenever more than one record could match, so that you get a predictable result.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
SalesforceQueryFirst( Sf,
"SELECT Id, Name FROM Account WHERE Name = " &
SalesforceSoqlQuote( Account_name ) &
" ORDER BY LastModifiedDate DESC LIMIT 1" )
</pre>

[[Parameter types]]: <code>SalesforceQueryFirst(sf; soql: Text)</code>

=== <span id="SalesforceCount">SalesforceCount(sf, soql, ''include_deleted'')</span> ===

Returns the query's <code>totalSize</code> as a number, so you don't have to retrieve and inspect the record list to count matches.

Example:
:<code>SalesforceCount( Sf, "SELECT Id FROM Opportunity WHERE IsClosed = false" )</code> → <code>42</code>

[[Parameter types]]: <code>SalesforceCount(sf; soql: Text; include_deleted := False)</code>

=== <span id="SalesforceQueryPage">SalesforceQueryPage(sf, soql_or_next_url, ''include_deleted'')</span> ===

Retrieves exactly one query page. Pass a SOQL expression to get the first page, or the <code>next_records_url</code> from a previous result to get the page after it.

Most models should use [[#SalesforceQuery|SalesforceQuery]](), which handles pagination for you. Use this function when your model deliberately needs page-by-page control.

[[Parameter types]]: <code>SalesforceQueryPage(sf; soql_or_next_url: Text; include_deleted := False)</code>

== Record functions ==

=== <span id="SalesforceGetRecord">SalesforceGetRecord(sf, sobject, record_id, fields)</span> ===

Retrieves one record, given its Salesforce object API name and record ID. It returns the record Struct itself, not a query-result wrapper.

* «record_id» must be a 15- or 18-character Salesforce ID.
* «fields» is a comma-separated list of field API names.

Example:
:<code>SalesforceGetRecord( Sf, "Account", Account_id, "Id, Name, Industry, BillingCountry" )</code>

[[Parameter types]]: <code>SalesforceGetRecord(sf; sobject: Text; record_id: Text; fields: Text)</code>

=== <span id="SalesforceGetRecords">SalesforceGetRecords(sf, sobject, record_ids, fields)</span> ===

Retrieves several records from a list of Salesforce record IDs, and returns a list of record Structs. Internally it builds a SOQL <code>IN (...)</code> condition from the IDs.

Example:
:<code>SalesforceGetRecords( Sf, "Contact", Contact_ids, "Id, Name, Email" )</code>

[[Parameter types]]: <code>SalesforceGetRecords(sf; sobject: Text; record_ids: List; fields: Text)</code>

=== <span id="SalesforceField">SalesforceField(record, field_path, ''default_value'')</span> ===

Reads a field from a Salesforce record Struct when the field name is a text value. A dotted «field_path» traverses relationship Structs.

Examples:
:<code>SalesforceField( Contact_record, "Email" )</code>
:<code>SalesforceField( Contact_record, "Account.Name", "No account" )</code>

It returns «default_value», <code>Null</code> by default, when the member is absent or it can't traverse the path.

When you already know the field name as you write the Definition, direct Struct access is simpler:
:<code>Contact_record -> Email</code>

Use <code>SalesforceField</code> for dynamic field names, dotted paths, or when you want a controlled default.

[[Parameter types]]: <code>SalesforceField(record; field_path: Text; default_value := Null)</code>

== Quoting text values ==

=== <span id="SalesforceSoqlQuote">SalesforceSoqlQuote(value)</span> ===

Escapes a text value as a SOQL string literal and surrounds it with single quotes, handling quotes, backslashes, and control characters.

Example:
:<code>"Name = " & SalesforceSoqlQuote( Customer_name )</code>

If <code>Customer_name</code> is <code>O'Reilly</code>, this produces a valid quoted SOQL literal instead of letting the apostrophe terminate the value early.

Use this function for '''values only'''. You can't safely turn Salesforce object or field API names into identifiers by quoting them -- the library validates those names instead.

[[Intelligent Arrays|Array abstraction]] applies, so it also quotes a list of values. [[#SalesforceGetRecords|SalesforceGetRecords]]() relies on this when it builds its <code>IN (...)</code> condition.

[[Parameter types]]: <code>SalesforceSoqlQuote(value: Text)</code>

== Metadata functions ==

These functions help you discover the API names and properties available to the authenticated integration user.

=== <span id="SalesforceObjects">SalesforceObjects(sf)</span> ===

Returns a list of summary Structs for the Salesforce objects that the authenticated user can see.

Example:
:<code>SalesforceObjects( Sf )</code>

Useful members usually include the object's API <code>name</code>, its display <code>label</code>, and capability flags. Salesforce supplies the exact members, which vary by API release and object type.

[[Parameter types]]: <code>SalesforceObjects(sf)</code>

=== <span id="SalesforceDescribe">SalesforceDescribe(sf, sobject)</span> ===

Returns Salesforce's full metadata description for an object, including its fields, relationships, picklist entries, and access capabilities.

Example:
:<code>SalesforceDescribe( Sf, "Opportunity" )</code>

[[Parameter types]]: <code>SalesforceDescribe(sf; sobject: Text)</code>

=== <span id="SalesforceFields">SalesforceFields(sf, sobject)</span> ===

Returns just the list of field metadata Structs from [[#SalesforceDescribe|SalesforceDescribe]](). Use it to find field API names, types, labels, whether a field can be filtered, and its allowed picklist values.

Example:
:<code>SalesforceFields( Sf, "Account" )</code>

[[Parameter types]]: <code>SalesforceFields(sf; sobject: Text)</code>

== Search ==

=== <span id="SalesforceSearch">SalesforceSearch(sf, sosl)</span> ===

Runs a Salesforce Object Search Language (SOSL) expression and returns its <code>searchRecords</code> list.

SOQL queries known objects and fields; SOSL searches text across one or more objects. Use <code>SalesforceSearch</code> when your search spans object types, or when it resembles a text search more than a structured query.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
SalesforceSearch( Sf,
"FIND {Acme} IN NAME FIELDS " &
"RETURNING Account(Id, Name), Contact(Id, Name, Email)" )
</pre>

For the full SOSL syntax, see the Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference].

[[Parameter types]]: <code>SalesforceSearch(sf; sosl: Text)</code>

== Working with returned records ==

The library represents Salesforce JSON objects as Analytica [[Struct]]s, and collections as lists. Given:

<pre style="background:white; border:white; margin-left: 1em;">
Variable Result ::= SalesforceSelect( Sf, "Account", "Id, Name, Owner.Name",
where: "BillingCountry = " & SalesforceSoqlQuote( Country ),
order_by: "Name",
row_limit: 100 )
</pre>

the records are:
:<code>Result -> records</code>

the first record is:
:<code>Result -> records[@=1]</code>

and you can read a field directly:
:<code>Result -> records[@=1] -> Name</code>

or through the helper, which also handles the dotted relationship path:
:<code>SalesforceField( Result -> records[@=1], "Owner.Name" )</code>

To build an array from the record list, introduce an [[Index]] for the record position and extract the members you want over that Index.

== Error handling and troubleshooting ==

The library raises an Analytica error when authentication fails, when Salesforce returns an unsuccessful HTTP status, when a record ID is malformed, when an object or field API name is invalid, or when a query exceeds «max_pages».

Common causes:
; Authentication fails
: With [[#ClientCredentialsAuth|ClientCredentialsAuth]](), check the login URL, the consumer key and secret, the client-credentials setting, the '''Run As''' user, and the app authorization.
; [[#SFLogin|SFLogin]]() fails
: Make sure you completed the sign-in in the browser window it opened, and that nothing else on your computer is using port 18756. If your organization restricts which connected or external client apps its users may authorize, ask your Salesforce administrator to allow '''Desktop Analytica'''.
; <code>INVALID_FIELD</code>, or an unknown field
: Use [[#SalesforceFields|SalesforceFields]]() to check the field's API name. The display label is often not the API name.
; Insufficient access
: Check the integration user's API permission, object permissions, field-level security, sharing access, and permission-set assignments.
; No records returned
: Try a simpler query, confirm the integration user can see the records, and inspect <code>total_size</code> in the query-result Struct.
; Query exceeds «max_pages»
: Add a selective <code>WHERE</code> clause or a <code>LIMIT</code>. Raise «max_pages» only when you intend the larger transfer.
; Sandbox authentication fails
: Use <code>"https://test.salesforce.com"</code>, unless your organization requires a specific My Domain login URL. [[#SFLogin|SFLogin]]() signs in to production only.
; The network request fails
: Confirm that the computer running Analytica reaches the Salesforce login and instance domains over HTTPS, and that any proxy or firewall permits the requests.

An HTTP 401 gets its own message asking you to recalculate the authentication and the connection, then retry -- the access token has expired or been revoked. With [[#SFLogin|SFLogin]](), recalculating it signs you in again.

== Function summary ==

:{| class=wikitable
! Function
! Purpose
|-
| [[#SFLogin|SFLogin]]()
| Sign in through your browser, and return the connection Struct
|-
| [[#ClientCredentialsAuth|ClientCredentialsAuth]]()
| Authenticate with the OAuth 2.0 client-credentials flow
|-
| [[#Salesforce|Salesforce]]()
| Create the REST connection Struct
|-
| [[#SoapLoginAuth|SoapLoginAuth]]()
| Legacy SOAP authentication. Migrate before 1-Jun-2027
|-
| [[#SalesforceSelect|SalesforceSelect]]()
| Build and run a common SOQL <code>SELECT</code>
|-
| [[#SalesforceQuery|SalesforceQuery]]()
| Run complete SOQL and retrieve all pages
|-
| [[#SalesforceQueryFirst|SalesforceQueryFirst]]()
| Return the first matching record, or <code>Null</code>
|-
| [[#SalesforceCount|SalesforceCount]]()
| Return the total matching-record count
|-
| [[#SalesforceQueryPage|SalesforceQueryPage]]()
| Retrieve one query page manually
|-
| [[#SalesforceGetRecord|SalesforceGetRecord]]()
| Retrieve one record by ID
|-
| [[#SalesforceGetRecords|SalesforceGetRecords]]()
| Retrieve several records from a list of IDs
|-
| [[#SalesforceField|SalesforceField]]()
| Read a dynamic or dotted field path from a record
|-
| [[#SalesforceSoqlQuote|SalesforceSoqlQuote]]()
| Quote a text value safely for SOQL
|-
| [[#SalesforceObjects|SalesforceObjects]]()
| List the objects visible to the authenticated user
|-
| [[#SalesforceDescribe|SalesforceDescribe]]()
| Retrieve full metadata for an object
|-
| [[#SalesforceFields|SalesforceFields]]()
| List the field metadata for an object
|-
| [[#SalesforceSearch|SalesforceSearch]]()
| Run SOSL and return the search records
|}

== History ==

The Salesforce REST library was introduced in August 2026, and requires [[Analytica 7.1]] or later. [[#SFLogin|SFLogin]]() was added in September 2026. The Constant <code>Salesforce_library_version</code> in the library holds its version number, currently <code>1.01</code>.

== See also ==

* [[ReadFromUrl]]() -- the function this library is built on
* [[ParseJSON]]() -- parses the JSON that Salesforce returns
* [[Struct]] -- the data structure used for connections, records, and query results
* [[Additional libraries]]
* [[OpenAI API library]]
* [[Database library]]
* Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference]
* Salesforce [https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-client-credentials-flow.html OAuth 2.0 Client Credentials Flow]

Salesforce REST library

2026-09-30T19:21:58Z

Lchrisman: Changed version #

[[Category:Function libraries]]
[[Category:Integration Functions]]

{{ReleaseBar}}

''Requires [[Analytica 7.1]] {{Analytica Developer}} edition or better.''

The '''Salesforce REST library''' lets your model authenticate with [https://www.salesforce.com/ Salesforce] and read Salesforce records and metadata through the Salesforce REST API, version 67.0. Use it to pull live data -- accounts, contacts, opportunities, or your own custom objects -- straight into an Analytica model, so that your analysis works from current CRM data instead of an exported snapshot.

It provides:
* OAuth 2.0 client-credentials authentication for unattended, server-to-server use
* A legacy SOAP-login option as a temporary migration bridge
* SOQL query execution, including automatic pagination
* Record-selection and record-retrieval helpers
* Salesforce object and field metadata
* SOSL search

This library reads from Salesforce. It has no functions to create, update, or delete Salesforce records.

'''Download:''' [[media:Salesforce REST library.ana|Salesforce REST library.ana]] (v. 1.02)

== Requirements ==

To use this library, you need:
* [[Analytica 7.1]] or later, {{Analytica Developer}} edition or better. The library is built on [[ReadFromUrl]](), which is not available in the Professional or Player editions.
* A Salesforce account, and an OAuth client configured in Salesforce (see [[#Setting up Salesforce for client-credentials authentication|Setting up Salesforce]] below).
* Internet access allowing Analytica to reach your Salesforce login and instance domains over HTTPS. If you have a strong firewall, you may need to add a rule to allow this.

== Getting started ==

# [[media:Salesforce REST library.ana|Download the library]] and save it into your <code>"C:\Program Files\Lumina\Analytica 7.1\Libraries"</code> folder.
# Launch Analytica and open your model, or start a new one.
# Select '''Add Library...''' from the '''File''' menu, select <code>Salesforce REST library.ana</code>, click '''OK''', select '''Link''', then click '''OK'''.

A typical model then uses three Variables -- an authentication Struct, a connection Struct, and one or more query results:

<pre style="background:white; border:white; margin-left: 1em;">
Variable Sf_auth ::= ClientCredentialsAuth(
"https://login.salesforce.com",
Sf_client_id,
Sf_client_secret )

Variable Sf ::= Salesforce( Sf_auth )

Variable Active_accounts ::= SalesforceSelect( Sf, "Account", "Id, Name, Industry",
where: "IsDeleted = false",
order_by: "Name",
row_limit: 100 )
</pre>

<code>Active_accounts</code> is a query-result [[Struct]]. Its list of records is:
:<code>Active_accounts -> records</code>

To read a field from the first record:
:<code>SalesforceField( Active_accounts -> records[@=1], "Name" )</code>

When you authenticate to a sandbox, use <code>"https://test.salesforce.com"</code> in place of <code>"https://login.salesforce.com"</code>.

== A brief introduction to SOQL ==

Salesforce Object Query Language (SOQL) resembles SQL, but it queries Salesforce objects and fields by their '''API names''' rather than by table and column names. A basic query looks like this:

<pre style="background:white; border:white; margin-left: 1em;">
SELECT Id, Name, Industry
FROM Account
WHERE Industry = 'Technology'
ORDER BY Name
LIMIT 100
</pre>

Standard object names include <code>Account</code>, <code>Contact</code>, and <code>Opportunity</code>. API names of custom objects and custom fields usually end in <code>__c</code> -- for example <code>License__c</code> or <code>Expiration_Date__c</code>. An object's API name is often not the same as the label you see in the Salesforce user interface, so use [[#SalesforceObjects|SalesforceObjects]]() and [[#SalesforceFields|SalesforceFields]]() to discover the names you need.

Whenever you insert a text value into a SOQL expression, quote it with [[#SalesforceSoqlQuote|SalesforceSoqlQuote]](). Don't use that function for object or field API names.

For the full language, see the Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference].

== Setting up Salesforce for client-credentials authentication ==

[[#ClientCredentialsAuth|ClientCredentialsAuth]]() is meant for unattended, server-to-server access. It needs an OAuth client configured in Salesforce, plus a dedicated Salesforce user whose permissions the integration runs under.

Salesforce terminology and Setup screens vary by edition and release. In current releases the OAuth client is normally an '''External Client App'''; some organizations still use a '''Connected App'''.

A Salesforce administrator generally needs to:
# Create an '''External Client App''' in Salesforce Setup.
# Enable '''OAuth settings''' and the '''OAuth 2.0 Client Credentials Flow'''.
# Grant the OAuth scope needed for REST access, normally '''Manage user data via APIs''' (<code>api</code>). Avoid broader scopes unless you need them.
# Save the app, then copy its '''Consumer Key''' and '''Consumer Secret'''. These become the «client_id» and «client_secret» parameters in Analytica.
# In the app's OAuth policies, select a dedicated '''Run As''' integration user for the client-credentials flow. Depending on the app type, Salesforce may also require '''Admin approved users are pre-authorized'''.
# Give the integration user the permissions your model needs -- API access, plus read access to the required objects and fields. Prefer permission sets and least privilege.
# If the app uses pre-authorization, assign the app's permission set or profile authorization to the integration user.

The library sends the token request to:
:<code>https://login.salesforce.com/services/oauth2/token</code>
or, for a sandbox:
:<code>https://test.salesforce.com/services/oauth2/token</code>

Salesforce returns an access token and the instance URL that the library uses for all later requests.

For current Salesforce-side details, see the Salesforce [https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-client-credentials-flow.html OAuth 2.0 Client Credentials Flow] documentation.

=== Protect the client secret ===

The consumer secret grants access as the configured integration user. Don't save it in a model that you distribute to people who shouldn't have the credential, and don't commit it to source control. Where you can, obtain it at deployment time from your organization's approved secret-management mechanism.

== Authentication and connection ==

=== <span id="ClientCredentialsAuth">ClientCredentialsAuth(login_url, client_id, client_secret)</span> ===

Authenticates using the OAuth 2.0 client-credentials flow and returns a [[Struct]] holding the access token.

:{| class=wikitable
! Parameter
! Meaning
|-
| «login_url»
| <code>"https://login.salesforce.com"</code> for production, or <code>"https://test.salesforce.com"</code> for a sandbox
|-
| «client_id»
| Consumer key from the Salesforce External Client App or Connected App
|-
| «client_secret»
| Consumer secret from the same app
|}

The Struct it returns contains these members:
* <code>access_token</code>
* <code>instance_url</code>
* <code>status_code</code>
* <code>status_text</code>
* <code>raw_response</code>

Example:
:<code>ClientCredentialsAuth( "https://login.salesforce.com", Sf_client_id, Sf_client_secret )</code>

When authentication fails, it reports an Analytica error that includes the HTTP status and the Salesforce response.

[[Parameter types]]: <code>ClientCredentialsAuth(login_url: Text; client_id: Text; client_secret: Text)</code>

=== <span id="Salesforce">Salesforce(auth)</span> ===

Creates the connection Struct that you pass to every query, record, search, and metadata function. «auth» is the Struct returned by [[#ClientCredentialsAuth|ClientCredentialsAuth]]() or [[#SoapLoginAuth|SoapLoginAuth]]().

The Struct it returns contains these members:
* <code>api_version</code> -- <code>"67.0"</code>
* <code>instance_url</code>
* <code>access_token</code>
* <code>rest_base_url</code>

Example:
:<code>Salesforce( Sf_auth )</code>

It's usually clearer to define the authentication and the connection as separate Variables, as shown in [[#Getting started|Getting started]], so that you can inspect an authentication failure on its own. You can also nest the calls:

<pre style="background:white; border:white; margin-left: 1em;">
Salesforce(
ClientCredentialsAuth(
"https://login.salesforce.com",
Sf_client_id,
Sf_client_secret ) )
</pre>

All REST calls use API version 67.0, including calls authenticated through [[#SoapLoginAuth|SoapLoginAuth]]().

[[Parameter types]]: <code>Salesforce(auth)</code>

=== <span id="SoapLoginAuth">SoapLoginAuth(login_url, username, password, security_token)</span> ===

Logs in with the legacy Salesforce SOAP Partner API <code>login()</code> call and returns a Struct whose session ID the REST functions use as a bearer token.

«security_token» is the Salesforce security token for that user account. The function concatenates it onto the password, as SOAP login requires.

'''This authentication method is a migration bridge only.''' Salesforce retires the SOAP <code>login()</code> mechanism on '''1-Jun-2027''', after which this function stops working. Write new models against [[#ClientCredentialsAuth|ClientCredentialsAuth]](), and migrate existing ones before that date.

[[Parameter types]]: <code>SoapLoginAuth(login_url: Text; username: Text; password: Text; security_token: Text)</code>

== Query functions ==

=== <span id="SalesforceSelect">SalesforceSelect(sf, sobject, fields, ''where, order_by, row_limit'')</span> ===

Builds and runs a common SOQL <code>SELECT</code>. This is the easiest entry point when your query has a straightforward <code>WHERE</code>, <code>ORDER BY</code>, and <code>LIMIT</code> structure. It returns the same query-result Struct as [[#SalesforceQuery|SalesforceQuery]]().

:{| class=wikitable
! Parameter
! Meaning
|-
| «sf»
| The connection returned by [[#Salesforce|Salesforce]]()
|-
| «sobject»
| Salesforce object API name, such as <code>"Account"</code>
|-
| «fields»
| Comma-separated field API names
|-
| «where»
| Optional SOQL condition, without the <code>WHERE</code> keyword
|-
| «order_by»
| Optional ordering expression, without the <code>ORDER BY</code> keywords
|-
| «row_limit»
| Optional maximum number of records. <code>0</code>, the default, applies no explicit limit
|}

The three optional parameters are declared <code>Named</code>, so pass them by name:

<pre style="background:white; border:white; margin-left: 1em;">
SalesforceSelect( Sf, "Contact", "Id, Name, Email, Account.Name",
where: "Email = " & SalesforceSoqlQuote( Target_email ),
order_by: "Name",
row_limit: 20 )
</pre>

It validates the object and field API names, but «where» and «order_by» are SOQL fragments that you supply. Quote any text value you interpolate into them with [[#SalesforceSoqlQuote|SalesforceSoqlQuote]](), as in the example above.

[[Parameter types]]: <code>SalesforceSelect(sf; sobject: Text; fields: Text; where: Named Text := ""; order_by: Named Text := ""; row_limit: Named Number := 0)</code>

=== <span id="SalesforceQuery">SalesforceQuery(sf, soql, ''include_deleted, max_pages'')</span> ===

Runs a complete SOQL expression and follows Salesforce pagination until it has retrieved every page.

It returns a query-result Struct with these members:

:{| class=wikitable
! Member
! Meaning
|-
| <code>records</code>
| List of parsed Salesforce record Structs
|-
| <code>total_size</code>
| Total matching records, as reported by Salesforce
|-
| <code>pages</code>
| Number of pages retrieved
|-
| <code>done</code>
| Whether Salesforce reported the query complete
|-
| <code>next_records_url</code>
| URL of a subsequent page. Normally <code>Null</code> once the query is complete
|-
| <code>raw_response</code>
| Raw response for the final page
|}

Set «include_deleted» to <code>True</code> to use Salesforce's query-all behavior, which can include deleted and archived records where Salesforce supports it.

«max_pages», 100 by default, protects your model from an unexpectedly large or insufficiently bounded query. If the result needs more pages than this, it raises an error rather than quietly returning an incomplete result.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
Local soql := "SELECT Id, Name, Amount, CloseDate " &
"FROM Opportunity " &
"WHERE IsClosed = false " &
"ORDER BY CloseDate";
SalesforceQuery( Sf, soql )
</pre>

[[Parameter types]]: <code>SalesforceQuery(sf; soql: Text; include_deleted := False; max_pages: Number := 100)</code>

=== <span id="SalesforceQueryFirst">SalesforceQueryFirst(sf, soql)</span> ===

Runs a SOQL expression and returns the first matching record Struct, or <code>Null</code> when nothing matches. Include an <code>ORDER BY</code> clause whenever more than one record could match, so that you get a predictable result.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
SalesforceQueryFirst( Sf,
"SELECT Id, Name FROM Account WHERE Name = " &
SalesforceSoqlQuote( Account_name ) &
" ORDER BY LastModifiedDate DESC LIMIT 1" )
</pre>

[[Parameter types]]: <code>SalesforceQueryFirst(sf; soql: Text)</code>

=== <span id="SalesforceCount">SalesforceCount(sf, soql, ''include_deleted'')</span> ===

Returns the query's <code>totalSize</code> as a number, so you don't have to retrieve and inspect the record list to count matches.

Example:
:<code>SalesforceCount( Sf, "SELECT Id FROM Opportunity WHERE IsClosed = false" )</code> → <code>42</code>

[[Parameter types]]: <code>SalesforceCount(sf; soql: Text; include_deleted := False)</code>

=== <span id="SalesforceQueryPage">SalesforceQueryPage(sf, soql_or_next_url, ''include_deleted'')</span> ===

Retrieves exactly one query page. Pass a SOQL expression to get the first page, or the <code>next_records_url</code> from a previous result to get the page after it.

Most models should use [[#SalesforceQuery|SalesforceQuery]](), which handles pagination for you. Use this function when your model deliberately needs page-by-page control.

[[Parameter types]]: <code>SalesforceQueryPage(sf; soql_or_next_url: Text; include_deleted := False)</code>

== Record functions ==

=== <span id="SalesforceGetRecord">SalesforceGetRecord(sf, sobject, record_id, fields)</span> ===

Retrieves one record, given its Salesforce object API name and record ID. It returns the record Struct itself, not a query-result wrapper.

* «record_id» must be a 15- or 18-character Salesforce ID.
* «fields» is a comma-separated list of field API names.

Example:
:<code>SalesforceGetRecord( Sf, "Account", Account_id, "Id, Name, Industry, BillingCountry" )</code>

[[Parameter types]]: <code>SalesforceGetRecord(sf; sobject: Text; record_id: Text; fields: Text)</code>

=== <span id="SalesforceGetRecords">SalesforceGetRecords(sf, sobject, record_ids, fields)</span> ===

Retrieves several records from a list of Salesforce record IDs, and returns a list of record Structs. Internally it builds a SOQL <code>IN (...)</code> condition from the IDs.

Example:
:<code>SalesforceGetRecords( Sf, "Contact", Contact_ids, "Id, Name, Email" )</code>

[[Parameter types]]: <code>SalesforceGetRecords(sf; sobject: Text; record_ids: List; fields: Text)</code>

=== <span id="SalesforceField">SalesforceField(record, field_path, ''default_value'')</span> ===

Reads a field from a Salesforce record Struct when the field name is a text value. A dotted «field_path» traverses relationship Structs.

Examples:
:<code>SalesforceField( Contact_record, "Email" )</code>
:<code>SalesforceField( Contact_record, "Account.Name", "No account" )</code>

It returns «default_value», <code>Null</code> by default, when the member is absent or it can't traverse the path.

When you already know the field name as you write the Definition, direct Struct access is simpler:
:<code>Contact_record -> Email</code>

Use <code>SalesforceField</code> for dynamic field names, dotted paths, or when you want a controlled default.

[[Parameter types]]: <code>SalesforceField(record; field_path: Text; default_value := Null)</code>

== Quoting text values ==

=== <span id="SalesforceSoqlQuote">SalesforceSoqlQuote(value)</span> ===

Escapes a text value as a SOQL string literal and surrounds it with single quotes, handling quotes, backslashes, and control characters.

Example:
:<code>"Name = " & SalesforceSoqlQuote( Customer_name )</code>

If <code>Customer_name</code> is <code>O'Reilly</code>, this produces a valid quoted SOQL literal instead of letting the apostrophe terminate the value early.

Use this function for '''values only'''. You can't safely turn Salesforce object or field API names into identifiers by quoting them -- the library validates those names instead.

[[Intelligent Arrays|Array abstraction]] applies, so it also quotes a list of values. [[#SalesforceGetRecords|SalesforceGetRecords]]() relies on this when it builds its <code>IN (...)</code> condition.

[[Parameter types]]: <code>SalesforceSoqlQuote(value: Text)</code>

== Metadata functions ==

These functions help you discover the API names and properties available to the authenticated integration user.

=== <span id="SalesforceObjects">SalesforceObjects(sf)</span> ===

Returns a list of summary Structs for the Salesforce objects that the authenticated user can see.

Example:
:<code>SalesforceObjects( Sf )</code>

Useful members usually include the object's API <code>name</code>, its display <code>label</code>, and capability flags. Salesforce supplies the exact members, which vary by API release and object type.

[[Parameter types]]: <code>SalesforceObjects(sf)</code>

=== <span id="SalesforceDescribe">SalesforceDescribe(sf, sobject)</span> ===

Returns Salesforce's full metadata description for an object, including its fields, relationships, picklist entries, and access capabilities.

Example:
:<code>SalesforceDescribe( Sf, "Opportunity" )</code>

[[Parameter types]]: <code>SalesforceDescribe(sf; sobject: Text)</code>

=== <span id="SalesforceFields">SalesforceFields(sf, sobject)</span> ===

Returns just the list of field metadata Structs from [[#SalesforceDescribe|SalesforceDescribe]](). Use it to find field API names, types, labels, whether a field can be filtered, and its allowed picklist values.

Example:
:<code>SalesforceFields( Sf, "Account" )</code>

[[Parameter types]]: <code>SalesforceFields(sf; sobject: Text)</code>

== Search ==

=== <span id="SalesforceSearch">SalesforceSearch(sf, sosl)</span> ===

Runs a Salesforce Object Search Language (SOSL) expression and returns its <code>searchRecords</code> list.

SOQL queries known objects and fields; SOSL searches text across one or more objects. Use <code>SalesforceSearch</code> when your search spans object types, or when it resembles a text search more than a structured query.

Example:
<pre style="background:white; border:white; margin-left: 1em;">
SalesforceSearch( Sf,
"FIND {Acme} IN NAME FIELDS " &
"RETURNING Account(Id, Name), Contact(Id, Name, Email)" )
</pre>

For the full SOSL syntax, see the Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference].

[[Parameter types]]: <code>SalesforceSearch(sf; sosl: Text)</code>

== Working with returned records ==

The library represents Salesforce JSON objects as Analytica [[Struct]]s, and collections as lists. Given:

<pre style="background:white; border:white; margin-left: 1em;">
Variable Result ::= SalesforceSelect( Sf, "Account", "Id, Name, Owner.Name",
where: "BillingCountry = " & SalesforceSoqlQuote( Country ),
order_by: "Name",
row_limit: 100 )
</pre>

the records are:
:<code>Result -> records</code>

the first record is:
:<code>Result -> records[@=1]</code>

and you can read a field directly:
:<code>Result -> records[@=1] -> Name</code>

or through the helper, which also handles the dotted relationship path:
:<code>SalesforceField( Result -> records[@=1], "Owner.Name" )</code>

To build an array from the record list, introduce an [[Index]] for the record position and extract the members you want over that Index.

== Error handling and troubleshooting ==

The library raises an Analytica error when authentication fails, when Salesforce returns an unsuccessful HTTP status, when a record ID is malformed, when an object or field API name is invalid, or when a query exceeds «max_pages».

Common causes:
; Authentication fails
: Check the login URL, the consumer key and secret, the client-credentials setting, the '''Run As''' user, and the app authorization.
; <code>INVALID_FIELD</code>, or an unknown field
: Use [[#SalesforceFields|SalesforceFields]]() to check the field's API name. The display label is often not the API name.
; Insufficient access
: Check the integration user's API permission, object permissions, field-level security, sharing access, and permission-set assignments.
; No records returned
: Try a simpler query, confirm the integration user can see the records, and inspect <code>total_size</code> in the query-result Struct.
; Query exceeds «max_pages»
: Add a selective <code>WHERE</code> clause or a <code>LIMIT</code>. Raise «max_pages» only when you intend the larger transfer.
; Sandbox authentication fails
: Use <code>"https://test.salesforce.com"</code>, unless your organization requires a specific My Domain login URL.
; The network request fails
: Confirm that the computer running Analytica reaches the Salesforce login and instance domains over HTTPS, and that any proxy or firewall permits the requests.

An HTTP 401 gets its own message asking you to recalculate the authentication and the connection, then retry -- the access token has expired or been revoked.

== Function summary ==

:{| class=wikitable
! Function
! Purpose
|-
| [[#ClientCredentialsAuth|ClientCredentialsAuth]]()
| Authenticate with the OAuth 2.0 client-credentials flow
|-
| [[#Salesforce|Salesforce]]()
| Create the REST connection Struct
|-
| [[#SoapLoginAuth|SoapLoginAuth]]()
| Legacy SOAP authentication. Migrate before 1-Jun-2027
|-
| [[#SalesforceSelect|SalesforceSelect]]()
| Build and run a common SOQL <code>SELECT</code>
|-
| [[#SalesforceQuery|SalesforceQuery]]()
| Run complete SOQL and retrieve all pages
|-
| [[#SalesforceQueryFirst|SalesforceQueryFirst]]()
| Return the first matching record, or <code>Null</code>
|-
| [[#SalesforceCount|SalesforceCount]]()
| Return the total matching-record count
|-
| [[#SalesforceQueryPage|SalesforceQueryPage]]()
| Retrieve one query page manually
|-
| [[#SalesforceGetRecord|SalesforceGetRecord]]()
| Retrieve one record by ID
|-
| [[#SalesforceGetRecords|SalesforceGetRecords]]()
| Retrieve several records from a list of IDs
|-
| [[#SalesforceField|SalesforceField]]()
| Read a dynamic or dotted field path from a record
|-
| [[#SalesforceSoqlQuote|SalesforceSoqlQuote]]()
| Quote a text value safely for SOQL
|-
| [[#SalesforceObjects|SalesforceObjects]]()
| List the objects visible to the authenticated user
|-
| [[#SalesforceDescribe|SalesforceDescribe]]()
| Retrieve full metadata for an object
|-
| [[#SalesforceFields|SalesforceFields]]()
| List the field metadata for an object
|-
| [[#SalesforceSearch|SalesforceSearch]]()
| Run SOSL and return the search records
|}

== History ==

The Salesforce REST library was introduced in August 2026, and requires [[Analytica 7.1]] or later. The Constant <code>Salesforce_library_version</code> in the library holds its version number, currently <code>1.01</code>.

== See also ==

* [[ReadFromUrl]]() -- the function this library is built on
* [[ParseJSON]]() -- parses the JSON that Salesforce returns
* [[Struct]] -- the data structure used for connections, records, and query results
* [[Additional libraries]]
* [[OpenAI API library]]
* [[Database library]]
* Salesforce [https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/ SOQL and SOSL Reference]
* Salesforce [https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-client-credentials-flow.html OAuth 2.0 Client Credentials Flow]

File:Salesforce REST library.ana

2026-09-30T19:20:35Z

Lchrisman: Lchrisman uploaded a new version of File:Salesforce REST library.ana

== Summary ==
The [[Salesforce REST library]] for Analytica -- a REST + JSON client for the Salesforce API v67.0. Supports OAuth 2.0 client-credentials authentication (and legacy SOAP login), paginated SOQL queries, record retrieval, SOSL search, and sObject metadata. Library version 1.01. Requires [[Analytica 7.1]] {{Analytica Developer}} edition or better.

File:Salesforce REST library.ana

2026-09-30T19:19:31Z

Lchrisman: Lchrisman reverted File:Salesforce REST library.ana to an old version

File:Salesforce REST library.ana

2026-09-30T19:18:06Z

Lchrisman: Lchrisman uploaded a new version of File:Salesforce REST library.ana

What's new in Analytica 7.2?

2026-09-28T13:42:14Z

Lchrisman:

Analytica 7.2 is the next release of Analytica and is currently in [[Beta Tester Page|beta testing]]. The current official release is [[Analytica 7.1]]. This page lists enhancements that are now to Analytica or ADE 7.2. To use Analytica 7.2 beta, please visit the [[Beta Tester Page]].

== Secrets ==
The [[Secret]] object class is a first-class home for the credentials your model uses: database passwords, API keys, bearer tokens.

A Secret keeps the credential itself out of the language entirely. The Secret's identifier evaluates to a ''placeholder'' text, e.g. <code><nowiki>{{secret:AcmeKey}}</nowiki></code>, which you compose into a connection string or URL like any other text:

:<code>DbQuery(f"DSN=AcmeWarehouse;UID=svc_reports;PWD={AcmeKey}", sql)</code>

The real value is substituted only inside allow-listed built-in functions ([[DbQuery]], [[ReadFromUrl|ReadFromURL]], [[OAuth2Authorize]], and the other database functions), in compiled code, just before the text goes to ODBC or to the web -- and only when the call's destination matches the Secret's declared policy. Definitions stay fully readable, with no cloaking or locked modules -- yet the credential never appears in any result, attribute, error message, or saved file, and model code cannot exfiltrate it (a <code>WriteTextFile</code> or a <code>ReadFromURL</code> aimed at some other server never sees the real value).

Create one with '''[[Object menu]] / New / Secret''' (requires the Developer edition; models ''containing'' secrets load and run in every edition). See [[Secret]] for the full story, including an honest account of what each storage kind does and does not protect against.

== Custom File Providers ==
(''advanced, esoteric'')
A [[Custom file system providers|file system provider]] makes a URI-style path, <code>«scheme»://«root»/«path»</code>, for example <code>"repo://Sales/Q3.csv"</code>, work anywhere the Analytica engine accepts a file name. The file provider can be a source other than a file system (for example, a git repo, cloud storage, a web-based document management system, etc.), but from Analytica and within your models, it can be used anywhere a file path would be used, as if it were a file. You have to configure the available file providers, and you can implement your own (e.g., to wrap an existing service) according to a document [[Custom file system providers/API spec|API specification]].

== GUI ==
* The [[Object menu]] has a new submenu named '''New''', which you can use to add a new object of any class. This makes it easier and more convenient to add more esoteric class instances that aren't on the toolbar (like Frame node, Struct, Callable, Secret, etc.) Plus it is easier to add a new node without using a mouse.
** '''[[Object menu]] / New / Picture''' prompts for an image filename. (similar to '''[File menu] / Import...'''.
* Enhancements to the [[Outline window]]
** There are now hover icons on line items.
** You can Alt+Click on an item in the Outline to insert its identifier while editing an expression elsewhere.
** The '''Module only''' checkbox has been removed from the header, and a new icon button added to each module line item to show or hide non-module children, allowing this to be controlled at the level of each module or library.
** Key strokes now have an effect. Up/Down arrows move between line items. Right/Left arrows from a module expand or collapse that item. Shift+Right/Left from a module show or hide non-module children. Home/End keys jump to the begging or end. And typing characters incrementally search among the items visible in the window.
* Input and Output popups are now present on Module nodes in a diagram. Input popups appear when you click to the immediately left of a node, and output popups appear when you click to the immediate right of a node. These have long existed for variables enabling you to quickly navigate dependencies, but for a Module node the situation is much more complex. A dependency exists from Module A to Module B when there exists a dependency between variables <code>X→Y</code> where X is within Module A and Y is within Module B. With modules, there can be a very large number of such dependencies, so the new module input/output popups are organized hierarchically with expanding outline views.
* There is a new [[Publish To Cloud dialog]]. It handles both ACP3 (the current version at https://acp.analytica.com at the time of this release) as well as ACP4 (coming soon).
* A user input node with a '''[List]''' control pops up a new list-editor dialog, similar to the one in ACP. Previously this opened the Object Window where you would edit the list. The new dialog focuses solely on the list without all the other attributes.
* Added Drag-and-drop of selected text within and between textual attribute values. Formerly required Cut-Paste, but differs in that Drag-and-drop doesn't alter the clipboard.
* The [[Preferences dialog]] exposes some new preference settings:
** The method used when generating identifiers from titles. (Which Assista will also use when naming objects)
** Whether display-only arrows should be show as dashed.
** The time zone used for new date-time values (such as when parsing dates).

== Built-in functions or structs ==
* The [[Functions To Read Excel Worksheets|Spreadsheet functions]] now work directly with live Google sheets.
* A new option to <code>[[SpreadsheetInfo]]( wb, 'Backend')</code>, to programatically detect which backend the workbook uses (<code>'LibXl'</code>, <code>'Excel'</code> or <code>'GoogleSheets'</code>).
* [[FileExists]]( filepath'', files, folders'' ) tests whether a file or folder exists, without the [[FileSystemListing]] idiom that this used to require. Requires {{Analytica Developer}} or better.
* New parameters, «map» and «includeNull» added to [[Flatten]] (...). Makes it easy and efficient to concatenate a collection of lists when the lists are behind [[references]] or in [[Struct]] members.
* [[SortIndex]], [[Sort]] and [[Rank]] can now accept a «lessThat» function for custom comparisons. See [[Using an ordering function when sorting]].
* A new optional «timeZone» parameter added to [[ParseDate]], [[ParseCSV]], [[NumberToText]], and [[Today]]. Controls which time zone a newly created date-time number (such as when parsed) is created in. [[ParseDate]] and [[ParseCSV]] now recognize ISO 8601 and RFC 3339 date-time format; These are used by many web services, and may include an explicit time zone, which gets converted into the active or specified time zone.
* Added new built-in functions for [[Encrypting and decrypting|encryption and decryption]] using strong, standard authenticated encryption. (requires [[Analytica Developer]] edition or better).
* (Esoteric) A new parameter, «sensitive», to [[AskMsgText]] and [[MsgBox]]. Used with the new <code>/AutomationTrace</code> [[Analytica Command Line|command line]] option to prevent sensitive info (like a credential or API key) from being logged.
* (''Experimental'') New [[Timer]] struct for scheduling an evaluation.
* New options for [[GetProcessInfo]] to detect non-Windows host version (e.g., when running on Linux), as well as installed fonts.
* (Esoteric) A new Struct, [[ArrowDependencies]], returns detailed information on dependencies into, or out of, nodes. Most useful for finding all the dependencies between two modules (i.e., which variables deep inside are responsible for dependencies between them). Introduce to enable Assista to better answer questions about module dependencies.
* The [[UncertainLMH]] distribution now allows «xLow»=«lb» or «xHigh»=«ub». This means that 10% (or more generally «pLow») of the probability sits at the «lb» or «ub» value creating a discontinuity in the CDF (an infinite spike in the PDF) at that value.
* Added an «asIndex» parameter to [[HandleFromIdentifier]]. The same already existed on [[Handle]]. Used to disambiguate in the case of a self-indexed array-valued variable.
* When <code>[[Area]](y,x)</code> or <code>[[Integrate]](y,x)</code> appear in a [[DefineOptimization]] formulation where <code>y</code> depends on decision variables, the analyzer recognizes this as a linear or quadratic relationship when deciding whether the problem is an «LP», «QP» or «NLP».

== Dates and time zones ==
* ISO 8601 / RFC 3339 date-times with a UTC offset, such as <code>2025-08-25T00:07:05.000+0000</code> (the form most web APIs return), are now parsed by [[ParseDate]], [[ParseCSV]], table cells and definitions, and can be written as literals inside expressions, e.g., <code>Sequence(2025-08-25T00:00:00, 2025-08-27T00:00:00, dateUnit: 'D')</code>. See [[Date and Time Values]].
* A new model preference, '''Time zone''' ([[Preferences dialog]]; system variable [[System variables#Sys_TimeZone|Sys_TimeZone]], default <code>'Local'</code>), says which time zone the model's date-time values are in. Text with an explicit offset is converted into it, and [[Today]]() reports the time in it.
* A new «timeZone» parameter on [[ParseDate]], [[ParseCSV]], [[Today]] and [[NumberToText]]: <code>'Model'</code>, <code>'Local'</code>, <code>'UTC'</code> or a fixed offset such as <code>'+05:30'</code>.
* A new date format, <code>'ISO8601'</code> (equivalent to <code>yyyy-MM-ddTHH:mm:ss.sssZ</code>), and date template codes <code>Z</code>, <code>ZZ</code> and <code>ZZZ</code> for the UTC offset, so timestamps can be sent back to an API: <code>NumberToText(x, dateFormat: 'ISO8601', timeZone: 'UTC')</code>. See [[Date formats]].
* '''Behavior change''': a trailing <code>Z</code> on a parsed date-time, e.g. <code>ParseDate('2025-08-25T00:07:05Z')</code>, was accepted but ignored in 7.0 and 7.1. It now means UTC, so such values shift by your zone's offset from UTC. A literal <code>Z</code> in a custom date template must now be quoted (<code>'Z'</code>).

== New command line options ==
See [[Analytica Command Line]].
*; <code>/evalThenExit:«expression»</code>: Like <code>/eval:</code>, but Analytica exits as soon as «expression» has finished, without asking whether to save changes. It replaces the <code>/eval:"«expression»;EvaluateScript('Bye -')"</code> idiom that a [[Running a model in a command line workflow|command line workflow]] used to need, and that was easy to forget.

*; <code>/lib:«YourLib.ana»</code>: Loads an Analytica library into [[SysLib_Customizations]], which exists concurrently with your model (in a different [[Namespace]]). It survives across model closures, so it can appear as new built-in functionality. Useful for [[MCP server in Analytica|MCP Servers]], QA testing, benchmarking, [[Running a model in a command line workflow|batch processing]], GUI extensions, General (model-independent) [[Assista - Analytica AI Assistant/Custom user skills for Assista|Custom Assista skill libraries]], etc.

*; <code>/Automation</code> and <code>/AutomationTrace:«file»</code>: Run in an [[Analytica_Command_Line/Automation|automation]] mode so that blocking modal dialogs don't appear waiting for a user input.

*; <code>/WindowXY</code> and <code>/WindowSize</code>: Explicit control over the initial location of the Analytica application window on your screen.

*; <code>/stores:«path to FileProvider.config»</code>: Location of a [[Custom file system providers|Custom file system provider]] configuration file.

*; <code>/remote-debugging-port:«port»</code> and <code>/remote-allow-origins:«origins»</code>: Hooks used by Lumina for Assista benchmarking and AI-assisted debugging during GUI development.

*; <code>/Autosave=0</code> or <code>/Autosave=1</code>: Turns the ''Maintain recovery info'' preference off or on for that run only, without changing the stored preference (and <code>/Automation</code> now implies <code>/Autosave=0</code>).

== AI Integration ==
* You can now use an [[MCP server in Analytica|MCP server implemented in desktop Analytica]] from Claude.ai, Claude CoWork and other AI clients that are running in the Cloud (when used in conjunction with a tunnel such as <code>cloudflared</code> or <code>ngrok</code>).

== Evaluation engine ==
* [[Null]] can be specified to a repeated index parameter, which is a way to specify the implicit dimension (aka the null index). All such repeated index parameters for all built-in functions handle this. This enables <code>...[[IndexesOf]](x)</code> to work when <code>x</code> has an implicit dimension without any extra surrounding code.
* Introduced a new function parameter qualifier, <code>nullIndexOk</code>, for a non-repeated index parameter. When this is specified, the caller can specify [[Null]] for the index with the meaning that the function should operate over the implicit dimension.

== Misc ==
* The limit on the maximum number of objects (which was 65500) has been removed. There is no longer any fixed limit.
* Dynamic calculations now use new attributes, <code>dynValue</code> and <code>dynProbValue</code> for partial results, and the usual <code>Value</code> and <code>probValue</code> only for fully computed results. Previously partial results during a dynamic calculation were tracked in <code>Value</code> and <code>probValue</code>.
* The identifier <code>Date</code> is no longer a reserved identifier, and hence can be used as an identifier in your own models. The previous attribute, which encodes "Created date" for models, modules, and libraries, is still present as <code>SysLib_Internal::Date</code>. Model file format is unchanged by this.

Functions to Write Data to Excel Worksheets

2026-09-24T19:17:52Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[Category:Excel to Analytica mappings]]
[[Category:Integration Functions]]

__TOC__
{{ReleaseBar}}

These functions write directly to an Excel spreadsheet. They complement the [[SpreadsheetCell]] and [[SpreadsheetRange]] functions for [[Functions To Read Excel Worksheets|reading data from Excel worksheets]]. They are a simpler alternative to [[OLE Linking]] or [[DbQuery|ODBC]], two other methods for sending data to spreadsheets. They are available only from the {{Developer}} edition or higher, including [[ADE]]. For the functions that read from Excel, see [[Functions To Read Excel Worksheets]].

These functions write the data to a spreadsheet when the function is evaluated. If upstream Analytica variables change, they won't automatically update the data in Excel until the variable (or button) that calls them is re-evaluated. In this way, they are different from outgoing [[OLE linking|OLE links]] which do update automatically if ''Auto recompute outgoing OLE links'' is set and the spreadsheet is currently loaded in Excel. These updates become permantent only when [[#SpreadsheetSave|SpreadsheetSave]] is called.

<div id="SpreadsheetSave" >
== SpreadsheetSave(workbook'', filename'') ==
</div>

Saves any changes to the «workbook» to the indicated filename, or to the original file if «filename» is omitted. The «filename» is interpreted relative to the [[CurrentDataFolder]]. The «workbook» must be an object obtained from [[SpreadsheetOpen]](). {{Release|1=7.2|2=|3=The original file, or «filename», can be a [[Custom file system providers|custom file system provider]] path such as <code>repo://Sales/Q3.xlsx</code>; the workbook is then uploaded to that store in one request.}}

<div id="SpreadsheetSetCell" >
== SpreadsheetSetCell(workbook, sheet, col, row, value) ==
</div>

Writes «value» (either a number or text) to the cell identified by «sheet», «col» and «row». You can write multiple values via array abstraction when «col», «row» and «value» share one or more indexes. The «workbook» must be an object obtained from [[SpreadsheetOpen]]().

For writing large arrays, [[#SpreadsheetSetRange|SpreadsheetSetRange]] runs faster.

It writes «value» into the formula of each cell. Thus, you can set an actual cell formula such as <code>"=Sum(D4:D24)"</code> by writing a
text values starting with <code>=</code>.

{{Release|1=7.1|2=|3=
=== Adding and removing sheets ===
You can add a new sheet or remove an existing sheet by using a <code>+</code> or <code>-</code> prefix on the «sheet» parameter:

:<code>SpreadsheetSetCell(wb, "+NewSheet", col, row, value)</code> — Adds a sheet named "NewSheet" to the workbook if it does not already exist (but uses the existing sheet if it does), then writes «value» to the specified cell. If «value» is Null, the sheet is added without writing any cell.
:<code>SpreadsheetSetCell(wb, "-OldSheet", col, row, Null)</code> — Removes the sheet named "OldSheet" from the workbook. The «col» and «row» parameters are required but ignored; «value» must be Null.

It is an error to add a sheet whose name already exists, or to remove the last remaining sheet from a workbook.
}}

=== Examples ===

For these examples we assume that, <code>Wb</code> is a variable defined as:
:<code>Variable Wb := SpreadsheetOpen("MyWorkbook.xls")</code>.

Either of the following two calls write the value <code>3.5</code> to cell <code>Sheet1!C5</code>. Note that «col» can use either the character label or the numeric column position:
:<code>SpreadsheetSetCell(Wb , "Sheet1", "C", 5, 3.5)</code>
:<code>SpreadsheetSetCell(Wb , "Sheet1", 3, 5, 3.5)</code>

Here A is a 1-D array indexed by <code>I</code>. Writes the array as a column-vector starting at cell <code>"D5"</code>:
:<code>SpreadsheetSetCell(Wb , "Sheet1", 4, 4+@I, A)</code>

Writes the same 1-D array as a row-vector starting at cell <code>"E1"</code>:
:<code>SpreadsheetSetCell(Wb , "Sheet1", "E", @I, A)</code>

Writes a 2-D array <code>B</code>, indexed by <code>I</code> and <code>J</code>, to the sheet with the upper-left corner at cell <code>B7</code>, with the <code>I</code> dimension on the horizontal, the <code>J</code> on the vertical:
:<code>SpreadsheetSetCell(Wb , "Sheet1", 1+@I, 6+@J, B)</code>

<div id="SpreadsheetSetRange" >

== SpreadsheetSetRange(workbook, range, value'', colIndex, rowIndex, sheet'') ==
</div>

Writes «value» to «range» in spreadsheet «workbook». «range» may be a named range, or a cell coordinate range, such as <code>'C6:F9'</code> or single cell <code>'C9'</code>. If it's a coordinate range, you must specify the «sheet», either within the coordinate range, such as <code>'Sheet1!C6: F9'</code> or using the optional «sheet» parameter , with sheet name as text or sheet number as a number from 1 to n.

«value» may be [[atomic]] -- i.e., a single number or text value -- or an array with 1 or 2 dimensions. If 1-D, you should specify either , «colIndex» or «rowIndex» as an index parameter. If2-D, you must specify both «colIndex» and «rowIndex».

Ideally, the target range matches the data with the same number of rows and columns. If the number of columns in «colIndex» exceeds the number of columns in «range» or «rowIndex» exceeds the number of rows, it will not write the extra columns or rows. If «value» has only one column, it repeats the same data for all rows in «range». If «value» has more than 1 column but less than the number of columns in «range»(or more than 1 row, but fewer than the number of rows in «range»), it writes <code>#N/A</code> into the extra cells in «range».

If value is text and begins with the <code>=</code> character, the spreadsheet will treat it as a formula, just as if you had typed the formula directly into the spreadsheet.

{{Release|1=7.1|2=|3=
=== Adding and removing sheets ===
You can add or remove sheets using a <code>+</code> or <code>-</code> prefix, either in the «range» parameter or in the «sheet» parameter.

'''Adding a sheet via «range»:'''
:<code>SpreadsheetSetRange(wb, "+NewSheet!A1:C3", data)</code> — Adds "NewSheet" and writes «data» to the range A1:C3 on it.
:<code>SpreadsheetSetRange(wb, "+NewSheet!", Null)</code> — Adds "NewSheet" without writing any data.

'''Removing a sheet via «range»:'''
:<code>SpreadsheetSetRange(wb, "-OldSheet!", Null)</code> — Removes "OldSheet" from the workbook.
:<code>SpreadsheetSetRange(wb, "-OldSheet", Null)</code> — Same (the trailing <code>!</code> is optional for removal).

'''Using the «sheet» parameter:'''
:<code>SpreadsheetSetRange(wb, "A1:C3", data, sheet:"+NewSheet")</code> — Adds "NewSheet" and writes data.
:<code>SpreadsheetSetRange(wb, "A1", Null, sheet:"-OldSheet")</code> — Removes "OldSheet"; «value» must be Null.

The sheet name cannot be specified with a <code>+</code>/<code>-</code> prefix in both «range» and «sheet» simultaneously. It is an error to add a sheet that already exists, or to remove the last remaining sheet.
}}

=== Examples ===

Writes the value <code>6.0</code> to the cell <code>Sheet1!B5</code>:
:<code>SpreadsheetSetRange(Wb , "Sheet1!B5", 6.0)</code>

Writes the 1-D array <code>Cash_flow</code> as a column-vector to a named range, already labelled as <code>"Cash_flow"</code>:
:<code>SpreadsheetSetRange(Wb , "Cash_flow", Cash_flow, Time)</code>

Writes a 1-D array <code>B</code>, indexed by <code>I</code>, as a row-vector, here in the third worksheet:
:<code>SpreadsheetSetRange(Wb , "D5:D15", B, , I, sheet: 3)</code>

Writes a 2-D array <code>ShippingCosts</code>, indexed by <code>Destination</code> and <code>Origin</code>, to the range labelled <code>"Shipping_costs"</code>:
:<code>SpreadsheetSetRange(Wb , "Shipping_costs", ShippingCosts, Destination, Origin)</code>

The next expression includes the row and column header labels with the data written by concatenating them to the data before the data is written to the range. The original array is in Variable <code>A</code> indexed by indexes <code>Row</code> and <code>Col</code>. Temporary index <code>R</code> and <code>C</code> prepend one item for the header row and column.
:<code>Index R:=Concat("",Row);</code>
:<code>Index C:= Concat("",Col);</code>
:<code>var temp := Concat([Row],A,,Col,C);</code>
:<code>var data := Concat([C],d1,,Row,R);</code>
:<code>SpreadsheetSetRange(Wb ,range,data,C,R)</code>

== SpreadsheetSetInfo(workbook, item, value) ==

SpreadsheetSetInfo lets you change properties of the workbook itself, as opposed to [[SpreadsheetSetCell]] and [[SpreadsheetSetRange]] which change properties or contents of cells. The «item» parameter must be one of these:
* <code>"ActiveSheet"</code> { Changes the selected sheet to the be one with the name «value» }
* <code>"Author"</code>
*<code> "CalculationMode"</code> { and «value» must be "Automatic", "Manual" or "Semiautomatic" }
* <code>"Date1904"</code>
*<code> "SelectedRange"</code> { makes the workbook and sheet visible if they aren't already, and selects the indicated cell range }
* <code>"Title"</code>

=== Examples ===
:<code>SpreadsheetSetInfo(wb, "ActiveSheet", "Sheet3")</code>
:<code>SpreadsheetSetInfo(wb, "CalculationMode", "Manual")</code>
:<code>SpreadsheetSetInfo(wb, "SelectedRange", "Sheet2!B3:E9")</code>

== History ==
In early 4.2 beta builds, before 4.2.0.21, these functions were present as [[SaveExcelWorkbook]], [[WriteWorksheetCell]] and [[WriteWorksheetRange]]. Those names have now been deprecated. They will still work for a while, but may be removed in a future Analytica build. Also, the parameters of [[SpreadsheetSetRange]] differ slightly from [[WriteWorksheetRange]] -- the «sheet» parameter has been made optional and moved from being the 2nd parameter to being the last parameter. It is now not necessary for named ranges.

== See Also ==
* [[Read and Write Spreadsheets]]
* [[Excel spreadsheets read and write]]
* [[Functions To Read Excel Worksheets]]
* [[Excel Functions from ADE]]
* [[Excel to Analytica Translation]]
* [[Excel to Analytica Mappings]]
* [[DbQuery|ODBC]]
* [[OLE Linking]]

Functions To Read Excel Worksheets

2026-09-24T19:17:52Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[Category:Excel to Analytica mappings]]
[[Category:Integration Functions]]

__TOC__
{{ReleaseBar}}

These functions let you open an Excel spreadsheet file, and read cells and ranges from it. For writing to a spreadsheet, see [[Functions to Write Data to Excel Worksheets]].

<div id="SpreadsheetOpen" >
== SpreadsheetOpen(filename'', showDialog, title{{Release|7.0||, backend}}{{Release|7.2||, account}}'') ==
</div>

Opens a spreadsheet file and returns a workbook object for use by other functions (such as [[SpreadsheetCell]] or [[SpreadsheetRange]]) to read from or write to the file.

The returned object displays in a result table as <code>«ExcelWorkbook»</code>{{Release|7.2||, <code>«GoogleSheetsWorkbook»</code> }}{{Release|7.0|| or <code>«LibXlWorkbook»</code>, depending on the «backend» used.}} {{Release|1=7.2|2=|3=A workbook opened from a native Google Sheet displays as <code>«GoogleSheetsWorkbook»,</code> but an Excel file stored in Google Drive displays as <code>«LibXlWorkbook»</code>.}}

{{Release|1=7.2|2=|3=«filename» can also be a [[Custom file system providers|custom file system provider]] path, such as <code>repo://Sales/Q3.xlsx</code>. The workbook is then read from that store and the LibXL backend is always used -- <code>backend: 'Excel'</code> is refused for such a path -- and [[SpreadsheetSave]] writes it back to the store.}}

Unless you include a complete file path in «filename», Analytica looks for the file in the [[CurrentDataFolder]]. You can also provide the name of a workbook that is currently open in Excel, even if it has not yet been saved to disk.

If you omit the optional parameter «showDialog», the file browser dialog opens only if the specified file cannot be found.
* Set «showDialog» to True (<code>1</code>) to force the file browser even if the file exists.
* Set «showDialog» to False (<code>0</code>) to suppress the dialog entirely.

If no file is successfully opened, the function flags an error. You can customize the file dialog caption by passing text to the optional «title» parameter.

[[SpreadsheetOpen]] can return two values: the workbook object and the full path to the file that was opened. This is particularly useful when the user selects a file via the dialog:
::<code>Local (wb, filePath) := SpreadsheetOpen("Data.xlsx");</code>
{{Release|1=7.0|2=|3=
{{Release|1=7.1|2=|3=
=== Creating a new workbook ===
If you pass <code>"New"</code> as the «filename», SpreadsheetOpen creates a new blank workbook with a single empty sheet, without saving to any file. This is useful for building a workbook from scratch before saving it with [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]].

:<code>SpreadsheetOpen("New")</code> — Creates a new workbook using the Excel backend.
:<code>SpreadsheetOpen("New", backend:'LibXl')</code> — Creates a new workbook using the LibXl backend.

You can then add sheets using the <code>+</code> prefix in [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetRange|SpreadsheetSetRange]] or [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetCell|SpreadsheetSetCell]], and save with SpreadsheetSave when done.
}}

=== Backend ===
''(New to [[Analytica 7.0]])''

The optional «backend» parameter determines which underlying engine Analytica uses to handle the spreadsheet.

* <code>'Excel'</code>: (Default) Uses the Microsoft Excel COM interface.
*;Requirements: Requires Microsoft Excel to be installed locally.
*;Capabilities: This backend includes the full Excel calculation engine. If you change cell values using [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]], formulas within the workbook will be recalculated, allowing you to read back computed results. It supports all standard Excel file formats and features.
*;Return type: Returns an «ExcelWorkbook» object.

* <code>'LibXl'</code>: Uses a built-in library for direct file access.
*; Requirements: Does not require Microsoft Excel to be installed.
*; Capabilities: Offers high performance for reading and writing raw data. It is ideal for automated environments (like servers) where Excel might not be present. Note that it does '''''not''''' include a calculation engine; it reads literal values and formulas from the file but cannot "re-calc" a workbook after data is changed.
*; Return type: Returns a «LibXlWorkbook» object.
{{Release|1=7.2|2=|3=

* <code>'GoogleSheets'</code>: Opens a Google Sheets spreadsheet, or an Excel workbook stored in Google Drive, from its link. It is selected automatically when «filename» is a <code>https://docs.google.com/spreadsheets/d/...</code> link (copy it from your browser's address bar while the sheet is open), so «backend» can be omitted.
*; Requirements: A Google account with access to the spreadsheet. The first time, Analytica opens your web browser so you can sign in to Google and select the spreadsheet in Google's file chooser; the connection is remembered on your computer under your Windows account, never in the model, and you can revoke it from your Google account settings. Analytica can open only the spreadsheets you select in that chooser (plus ones it creates itself), so a link to a spreadsheet the chooser did not show cannot be opened. Pass an empty «filename» (or «showDialog»: True) to browse for a spreadsheet.
*; Capabilities: Reads come from a snapshot taken when the workbook is opened. Writes made with [[SpreadsheetSetCell]] and [[SpreadsheetSetRange]], and sheets added or removed, are sent to Google when the computation finishes, when you call [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]](wb), or when the workbook is refreshed: <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code> sends the pending writes and re-downloads the spreadsheet, so the values Google computed (and other people's edits) are seen. A native Google Sheet is exported by Google as an .xlsx snapshot (Google limits the export to 10 MB); an Excel workbook stored in Drive is downloaded as-is and written back as a whole file. The tab names the model sees (<code>SpreadsheetInfo(wb, 'Sheets')</code>, and «sheet» given by name) are the names in the exported snapshot, truncated to 31 characters, while writes are addressed to Google's real tab titles. <code>SpreadsheetOpen("New", backend:'GoogleSheets', title: "My sheet")</code> creates a new Google Sheet in your Drive. The second return value is the spreadsheet's link.
*; Return type: Returns a «GoogleSheetsWorkbook» object for a native Google Sheet, or a «LibXlWorkbook» object for an Excel file stored in Drive. <code>SpreadsheetInfo(wb, 'Backend')</code> returns <code>'GoogleSheets'</code> or <code>'LibXl'</code> accordingly, and <code>SpreadsheetInfo(wb, 'URL')</code> and <code>SpreadsheetInfo(wb, 'Account')</code> give its link and the Google account it was opened with.
*; Advanced: Analytica identifies itself to Google as an application registered by Lumina. An organization that would rather it identified itself as an application of their own -- because their Google Workspace administrator controls which outside applications may reach their data, for example -- can arrange that; see [[Using your own Google OAuth client]], which also covers asking Google for access to every spreadsheet so that the chooser is never shown.
*; Unattended use: A server, a scheduled job or [[Analytica Decision Engine|ADE]] on a machine where nobody is present cannot answer a browser. Give «account» a Google service account instead, and share the spreadsheet with its e-mail address -- see [[Using a Google service account]].
*; Managing the connection: <code>SysLib_Internal::GoogleAccountEmail()</code> answers the Google account Analytica is connected to, or Null when there is none. <code>SysLib_Internal::DisconnectGoogleAccount()</code> revokes that access at Google and forgets the stored connection, returning the address it disconnected; it is a side effect, so evaluate it from a button's OnClick or the [[Typescript Window|Typescript window]] rather than in a Definition. Opening a spreadsheet again then reconnects, and <code>showDialog: True</code> forces the connect dialog if you want to switch accounts. You can also revoke Analytica's access from [https://myaccount.google.com/permissions your Google account's permissions page].
}}
}}
=== Example ===

:<code>SpreadsheetOpen("C:\MyModels\Sales Numbers.xlsx") → ''«ExcelWorkbook»''</code>

<div id="SpreadsheetCell"></div>

=== Getting the file name actually opened ===
Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. [[SpreadsheetOpen]] returns the file path as a second return value, which you can optionally capture using, e.g.,

:<code>[[Local]] (contents, filepath) := [[SpreadsheetOpen]]( ... );</code>

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using [[ComputedBy]] with the default filename as follows:

:Variable TheFilename ::=
::<code>[[ComputedBy]]( TheFileContetns, "defaultFilename.xlsx" ) </code>

:Variable TheWorkbook::=
::<code>( , TheFilename ) := [[SpreadsheetOpen]]( TheFilename )</code>

The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheWorkbook</code> is locally equivalent to:

:<code>[[Local]] (wb, filename ) := [[SpreadsheetOpen]]( TheFilename );</code>
:<code>TheFilename := filename;</code>
:<code>wb</code>

=== Use with Office 2010 ===

If you have installed the "Click-to-Run" version of Office 2010 from a web download, these spreadsheet functions may not work, due to a "feature" introduced in Office 2010 that apparently disables several common operations. In this case, you may need to re-install Office using the MSI-based edition. See how to do this at:

[http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx]

=== Excel 64-bit requires Analytica 64-bit ===

Analytica 32-bit cannot launch Excel 64-bit. (The other way around works). Thus, if you have installed Excel 64-bit (which we recommend), make sure you have installed Analytica 64-bit. If you are a [[Free Edition]] user, you probably have 32-bit installed, but you can install Analytica 64-bit from the [https://www.lumina.com/support/downloads/ Analytica Downloads page].

=== Remembering the selected filename ===

When [[SpreadsheetOpen]]() shows the file dialog and you select a file, it does not save the file name. So, the next time you load the model, you'll have to select the file again. If you want the model to remember the selected file, so it will just load it without asking, prompt using that file name as the default, you can use the '''SpreadsheetOpenEx''' function in the [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]].

=== Having same spreadsheet open in Excel at the same time ===

It is often useful to have the spreadsheet you are working with open in Excel at the same time your model is working with it. When you want to do this, is it best to open it Excel first, before evaluating [[SpreadsheetOpen]], in which case [[SpreadsheetOpen]] connects to the existing Excel process and to the currently open spreadsheet. If you change cells in Excel, then evaluate a spreadsheet read functions, you'll read the new values, and if your model writes to the spreadsheet, you'll see those values reflected immediately in the Excel interface.

When you call [[SpreadsheetOpen]] before opening the model in Excel, the situation is more complex. To understand what happens and how to view the same model in the Excel UI at the same time, see [[Simultaneously opening a spreadsheet in Excel and Analytica]].

=== SpreadsheetOpenFlags ===
A registry setting named <code>SpreadsheetOpenFlags</code> can be set to alter how [[SpreadsheetOpen]] connects to Excel and the initial settings in Excel. There is usually no reason to fiddle with these flags unless you encounter a specific problem. It has been more common to set these flags in server-based applications using ADE than from desktop Analytica.

You'll need to modify the sitting from RegEdit. You can set it in either
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
or
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
For ADE, set it in one of these hives:
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>

Setting it in HKLM causes it to apply from any account on your computer, while setting it from HKCU causes it to apply only to your own account. A setting in HKCU takes precedence over the same setting in HKLM.

Initially the value <code>SpreadsheetOpenFlags</code> will not be present. Create a new 32-bit DWORD with this name. The set the numeric value to an addition of any of these flags that you want:
* 1 = Launch using a COMCreateObject mechanism. (unset)=Launch using a BindToObject method.
*: A BindToObject method (the default for Desktop Analytica) makes it possible to connect to a Workbook running in an active Excel UI. A COMCreateObject mechanism launches a separate instance of Excel every time.
* 2 = Turn off Excel's Interactive flag.
* 4 = Turn off Excel's "Ask to update OLE links" flag.
* 8 = Turn off Excel's "Display Alerts"
* 16 = Disable Excel macros (for security)
* 32 = Close when visible.
*:Normally, if the workbook is currently visible in an Excel UI, Analytica simply disconnects from it, but doesn't force the workbook to close. The Excel UI is then responsible for eventually closing it. This overrides this and forces the workbook to close when the model releases it, even if it is visible.

=== From ADE ===
When using from ADE on a Web Server, we strongly advise against using Excel 2016 on the server. Excel 2010 works fairly well, but Excel 2016 is extremely unstable and has a tendency to fail unpredictably and lock up all other Excel instances. Microsoft responds by saying that Excel 2016 is not supported nor licensed for use on a web server.

When [[SpreadsheetOpen]] is evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the open completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

=== Debugging Errors ===
This section documents failures when '''SpreadsheetOpen''' has been unable to open Excel, and solutions.
* '''''Library not registered''''':
*:If this error occurs when '''SpreadsheetOpen''' is evaluated...
** The article [https://excel.tips.net/T002952_Library_Not_Registered_Error.html Library not registered error] explains how to solve this problem when it is caused by an Excel plug-in. It may be caused by a bad Excel add-in library. You should also run <code>excel.exe /regserver</code>.
** In one case, an Analytica user concluded that an older version of Excel was interfering with his newer 32-bit version of Excel. He uninstalled both and re-installed Excel 64-bit and the problem corrected itself. But, for a different user with this problem, these steps did not correct the problem.
** A common cause of this problem is when stray registry settings from Excel versions that had been installed and uninstalled interfere with your current version of Excel. This is most common after you roll back to an earlier release after uninstalling a later release. To test for this cause, start Power Shell and run:
**::<code>get-childitem -Path "HKLM:\Software\Classes\TypeLib\{00020813-0000-0000-C000-000000000046}"</code>
::If you see more than one version listed, with the most recent version number missing its mapping to Excel, then this is probably the cause. To fix, use <code>RegEdit</code> to delete the hive for the later version number.

== SpreadsheetCell(workbook, sheet, column, row'', what'') ==
</div>

Returns the value (or other information) of a cell of a worksheet given its coordinates. The function fully array abstracts, so you can get a range of cells by specifying the column and/or row as an array.

Parameters:
;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
;«sheet»: The name or number of a worksheet from the workbook. Number 1 is the first worksheet, etc.
:: If you specify <code>sheet: "*"</code>, it returns the cell value from ''column, row'' for all sheets in the workbook, indexed by <code>.Sheet</code>, a local index containing the names of the worksheets. This is a way to get a list of all the worksheets in the workbook. If you specify column and/or rows as arrays, you can also use this to get a 3D array for a range over all worksheets.
;«column»: The column label, e.g., <code>"A", "B"</code>, or <code>"AB"</code>, or the column number as an integer.
;«row»: The row number as an integer
;«what»: optional. Let's you get the formula or format information from the cell. See below under [[SpreadsheetRange]] for details.

If the worksheet cell is empty, it returns [[Null]]. It flags an error if «workbook» is not a valid workbook, if it does not contain «sheet», or if the coordinates are invalid.

=== Examples ===
These expressions are different ways to get the same result, the value from cell ''C7'' in the first sheet, <code>"Sheet1"</code> of workbook:
:<code>SpreadsheetCell(workbook, "Sheet1", "C", 7)</code>
:<code>SpreadsheetCell(workbook, "Sheet1", 3, 7)</code>
:<code>SpreadsheetCell(workbook, 1, 3, 7)</code>

Suppose the spreadsheet contains a 2-D table in the region ''C4:J19''. The columns of this table correspond to the years 2008..2015. The rows correspond to different assets. It is easier to refer to the columns by number, so that the columns "C" thru "J" are columns 3 thru 10. To hold this 2-D table, we need two indexes in Analytica, <code>Time</code> and <code>Asset</code>.

:<code>Index Time := 2008..2015</code>
:<code>Index Asset := 1..16</code>
:<code>Variable Workbook := SpreadsheetOpen("C:\Asset Data.xls")</code>
:<code>Variable Data := SpreadsheetCell( workbook, "Sheet1", @Time+2, @Asset+3)</code>

<div id="SpreadsheetRange">
== SpreadsheetRange(workbook, range'', colIndex, rowIndex, howToIndex, sheet, what'') ==
</div>

Returns the values (or other information) for a range of cells from an Excel worksheet. The «range» can be can be a cell address such as <code>"C7"</code> or cell range <code>"C7:F12"</code>, or the name of a range defined in the spreadsheet. If you want to read or write several cells or ranges in a spreadsheet, it is often convenient to use Excel's name mechanism and refer to them by name in Analytica.

If the range has multiple columns, the result has local index <code>.Column</code> unless you specify «colindex» as a parameter. Similarly, if the range has multiple rows, the result has local index <code>.Row</code> unless you specify «rowindex» as a parameter. Flags in «howToIndex» let you control whether the first row (column) should be used as labels for local index <code>.Row</code> or <code>.Column</code>.

If you specify a sheet name with no cells, e.g. <code>"Inputs!"</code>, it returns a table that includes all cells from that sheet that contain anything.

By default, it returns the number or text values from the range (or <code>NULL</code> if the cell is empty). You can use the «what» parameter to obtain the cell formula, address, format, styles, precedent, and dependent cells for each cell.

=== SpreadsheetRange Parameters ===

SpreadsheetRange has two required parameters:

;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
; «range»: A cell range. It may be a single cell address, e.g. <code>"B10"</code>, a range, e.g. <code>"A1:BC99"</code>, optionally with sheet name, e.g. <code>"Sheet1!A1:BC99"</code>, or a named range, e.g. <code>"Discount_rate"</code> defined in the spreadsheet. If the «range» doesn't mention the sheet name, you must specify «sheet» as a separate parameter.
:: If you specify the range as <code>"Sheet1!"</code>, with nothing after the "!", or omit «range» and specify only «sheet», it returns the smallest rectangular range that includes all used cells within the sheet.

SpreadsheetRange has four optional parameters relating to the indexes for a range with multiple columns or rows, or over multiple sheets:
;«colIndex»: (optional) An index to use for the column dimension of the result.
;«rowIndex»: (optional) An index to use for the row dimension of the result.
;«howToIndex»: (optional) Flags controlling how to index the result when «colIndex» or «rowIndex» are not specified. You can add any of these values to combine their effects:
::<code>1</code>: Force a column index even if the range spans only a single column. Has no effect if you specify «colIndex».
::<code> 2</code>: Force a row index even if the range spans only a single row. Has no effect if you specify «rowIndex».
::<code>4</code>: Use the first row of «range» as column labels in the local index <code>.Column</code>. Exclude this first row in the result returned.
::<code>8</code>: Use the first column of «range» as labels in the local index <code>.Row</code>. Exclude this first column in the result returned..
::<code>16</code>: Suppress the error message that is otherwise given if the sizes of «colIndex» or «rowIndex» do not match the size of the range.
;«sheet»: (optional) The name or number of a worksheet inside the workbook. It can be a list of sheets, in which case, the function will return a 3D table, indexed by this list as the third dimension.
;«what»: (optional) See below for details on this parameter.

=== Indexes of a cell range ===

The result may be a scalar (single cell), a column vector, a row vector, or a 2-D array, depending on the dimensions of the cell range. If the range has more than one row (or column), it will use a local index .Row (.Column) by default. By default, the elements of the .Row index contain the range's row numbers and elements of the column index contain its column labels. For example, if the range is <code>"C7:E12"</code>, <code>.Row</code> would contain the elements <code>[7, 8, 9, 10, 11, 12]</code> and <code>.Column</code> would contain <code>['C', 'D', 'E']</code>.

Or, you can use the first column (row) of the range as the values for the local index .Row (.Column), by specifying <code>howToIndex: 8</code> (<code>howToIndex: 4</code>, or <code>howToIndex: 12</code> for both .Row and .Column.) If you use, the first row (column) of the range as values of the local indexe(es), they will not be included in the value of the array returned. So, in that case, the range must have at least two rows (columns).

Alternatively, if you already have index(es), you can supply them to the «rowIndex» («colIndex») parameters. If you specify a «rowIndex» or «colIndex», that is shorter than the number of rows (columns) in the range, it truncates the result. If an index is too long, it pads the result with [[Null]]. In these cases, it gives a warning message unless you set flag <code>''howToIndex: 16''</code>.

If the range has just one column, the result normally will not have a local .Column index. But, you can force it to use a .Column with one element by setting <code>howToIndex: 1</code>. If you are using a named range and don't know how many columns it has, you might use this option to prevent an error occurring if you use [[Dot_operator::A.I|result.Column]] in an expression. Similarly, you can force it to use local <code>.Row</code> index even when the result has only a single row by specifying <code>howToIndex: 2</code>.

You can obtain the entire range of a worksheet with all cells that contain anything named <code>"Sheet1"</code> by specifying the «range» as <code>"Sheet1!"</code> or by omitting the «range» parameter and specifying just the «sheet» parameter.

=== Examples ===

The following examples use this spreadsheet:

:[[Image:WorksheetRange ExcelShot.jpg]]

This spreadsheet contains these named ranges:
:{| class="wikitable"
! Label !! Range
|-
| Rate || B1
|-
| Year || B3:F3
|-
| Cash_flow || B4:F4
|-
| Divisions || A7:A9
|-
| Employee_count || B7:F9
|}

:<code>SpreadsheetRange(wb, "Rate") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B1") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B3:F3") →</code>
:{| class="wikitable"
! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
| || 2008 || 2009 || 2010 || 2011 || 2012
|}

:<code>Index Year := CopyIndex( SpreadsheetRange(wb, "Year", howToIndex: 1));</code>
:<code>SpreadsheetRange(wb, "Cash_flow", colIndex: Year) →</code>
:{| class="wikitable"
! .Year → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
| || -100 || 10 || 30 || 50 || 60
|}

''Note'': <code>howToIndex: 1</code> was specified for <code>Year</code> here so that we would have a 1-D array even if only one year were present in the spreadsheet.

:<code>SpreadsheetRange(wb, "Employee_count") →</code>
:{| class="wikitable"
! !! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
! rowspan="3" | .Row<br>↓ !! 7
| 24 || 27 || 28 || 32 || 35
|-
! 8
| 13 || 13 || 13 || 13 || 13
|-
! 9
| 25 || 22 || 21 || 19 || 16
|}

:<code>Index Time := [2008, 2009, 2010, 2011, 2012];</code>
:<code>SpreadsheetRange(wb, "A7:F9", colIndex: Time, howToIndex: 8, sheet: 1) →</code>
:{| class="wikitable"
! !! Time → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
! rowspan="3" | .Row<br>↓ !! "Div A"
| 24 || 27 || 28 || 32 || 35
|-
! "Div B"
| 13 || 13 || 13 || 13 || 13
|-
! "Div C"
| 25 || 22 || 21 || 19 || 16
|}

To obtain the list of worksheet names:
:<code>SpreadsheetCell(wb, "*", 1, 1).Sheet</code>

To obtain all used cells in sheet named "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2")</code>

To obtain the number format of all cells in "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2", what:"NumberFormat")</code>

=== SpreadsheetRange «what» parameter ===

By default, SpreadsheetRange() returns the value of the cell(s) in the range, but you can use the «what» parameter to obtain the formula, cell style and formats, cell address, predecessor or dependent cells of each cell:
;«what»: (optional). By default, SpreadsheetRange returns the value of the range, but you can use this parameter to obtain its formula, or cell style parameters. Possible values:
::<code>"Value"</code>: (Default) The computed value. Excel dates become Analytica date-time numbers, which display as dates.
::<code>"NumericValue"</code>: The computed value, but dates are returned as numbers.
::<code>"Formula"</code>: The cell formula as a text value in the normal Excel format starting with "=", e.g., <code>"=Sum(D4:D10)"</code>
::<code>"RelativeFormula"</code>: The cell formula using relative offset format, e.g., <code>"=Sum(RC[-9]:R[+6]C[-9])"</code>

==== «what» parameter cell formats ====
::<code>"NumberFormat"</code>: The cell number format as text.
::<code>"BackColor"</code>: Cell background color as integer: ''red*65536 + green*256 + blue''
::<code>"Text Color"</code>: Font color as an integer: ''red*65536 + green*256 + blue''
::<code>"FontName"</code>: Name of the font used to display the cell
::<code>"FontSize"</code>: Point size of the font displayed in the cell
::<code>"FontStyle"</code>: Special font styles for cell separated by spaces, may include "bold italic underline strikethrough subscript superscript outline shadow"
::<code>"HorizontalAlignment"</code>: Text justification, one of: <code>'Left', 'Center', 'Right', 'Justify', 'Distributed', 'Fill'</code>. (''new to [[Analytica 5.0]]'')
::<code>"VerticalAlignment"</code>: Text vertical justification, one of: <code>'Top', 'Middle', 'Bottom', 'Justify', 'Distributed'</code>. (''new to [[Analytica 5.0]]'')
::<code>"WrapText"</code>: <code>0</code> or <code>1</code> controls whether text is word wrapped to fit in the cell.
::<code>"Border(Left|Right|Up|Down)"</code> show a border to left, right, above, or below the cell.
::<code>"Border(Left|Right|Up|Down)Color"</code>: Return the color of the specified side of the border as an RGB number -- E.g., <code>"BorderLeftColor"</code> returns an integer equal to ''red*65535+green*256+blue''
::<code>"Border (Left|Right|Up|Down) Style"</code>: Style of indicated border, or [[Null]] if not set. May be <code>"Solid", "Dash", "DashDot", "DashDotDot", "Dot", "Double"</code>, or <code>"SlantDashDot"</code>.
::<code>"Border (Left|Right|Up|Down) Weight"</code>: Thickness of indicated border, usually between 1 and 4

==== «what» parameter cell addresses ====
::<code>"Address"</code>: The address of the cell range, e.g., <code>"B12:C13"</code>
::<code>"AddressR1C1"</code>: The address of the cell range in R1C1 format, e.g., <code>"R12C2:R13C3"</code>
::<code>"Sheet"</code>: The sheet name where the cell range exists.
::<code>"RangeName"</code>: The name of the range, if it is a named range.

==== «what» parameter cell precedents and dependents ====

::<code>"DirectPrecedents"</code>: Addresses of all cells mentioned in the cell formula, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not precedents in other sheets.
::<code>"DirectPrecedentsRelative"</code>: Same as "DirectPrecedents", but cells are given by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"DirectDependents"</code>: Addresses of all cells whose formula mentions this cell, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not dependents in other sheets.
::<code>"DirectDependentsRelative"</code>: Same as <code>"DirectDependents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Precedents"</code>: Addresses of all cells in the current worksheet mentioned in the formula of this cell and the formulas of its direct precedents. It does not include cells reached by paths passing through other sheets.
::<code>"PrecedentsRelative"</code>: Same as <code>"Precedents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Descendants"</code>: Description of all cells in the current worksheet that depend directly or indirectly on the given cell. It does not include cells reached by paths passing through other sheets.
::<code>"DirectDescendantsRelative"</code>: Same as <code>"DirectDescendants"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.

=== Errors in SpreadsheetRange parameters ===
In a call to SpreadsheetRange(wb, range):
* If range refers to a sheet, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the worksheet 'sheet' was not found."
* If range refers to a named range, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the indicated named cell range, 'x', was not found."
* If range refers to a cell address with bad syntax, e.g. "ted!A1:R3C6", it gives an error message saying "the range named A1:R3C6 was not found in Excel worksheet 'ted'."

<div id="SpreadsheetInfo">
== SpreadsheetInfo(workbook, item) ==
</div>

SpreadsheetInfo gets various kinds of information about the spreadsheet («workbook») specified by parameter «item»:

{| class="wikitable"
! item !! Description
|-
| <code>"AcceptLabelsInFormulas"</code> || True when you can use labels in worksheet formulas. This is usually false.
|-
| <code>"Account"</code> || ''([[Analytica 7.2|7.2]])'' The Google account a workbook opened from Google Sheets or Google Drive is connected with. Null for other workbooks.
|-
| <code>"ActiveSheet"</code> || The number of the active (displayed) worksheet.
|-
| <code>"Author"</code> || The name of the author, usually the name of the person who created the spreadsheet as recorded by Windows OS.
|-
| <code>"Backend"</code> || ''([[Analytica 7.2|7.2]])'' Which engine holds the workbook: <code>'Excel'</code>, <code>'LibXl'</code> or <code>'GoogleSheets'</code> (see the «backend» parameter of [[SpreadsheetOpen]]).
|-
| <code>"CalculationMode"</code> || The calculation mode set for the workbook, which may be "Automatic", "Manual" or "Semiautomatic", meaning automatic except for data tables.
|-
| <code>"CalculationState"</code> || ''([[Analytica 5.0|5.0]])'' The current state of Excel's calculation engine, either <code>"Calculating"</code>, <code>"Pending"</code> or <code>"Done"</code>.
|-
| <code>"CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of the Excel calculation engine that the current workbook was last calculated in. If it was saved in an earlier version of Excel and hasn't yet been fully calculated, the value is 0. You can compare this to the "Excel.CalculationVersion" to determine whether it was last re-calculated using the same calculation engine as your current installed Excel.
|-
| <code>"CodeName"</code> ||
|-
| <code>"Date1904"</code> || The base for dates used in the workbook.
|-
| <code>"DecimalSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character used to separate a whole number from its fractional part. In English-speaking countries this is '.' (a dot).
|-
| <code>"Excel.CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of calculation engine for your installed version of Excel.
|-
| <code>"Filename"</code> || The name of the file, including the full file path.
|-
| <code>"Name"</code> || The name of the file, without the file path.
|-
| <code>"Names"</code> || A list of all the named ranges.
|-
| <code>"OperatingSystem"</code> || ''([[Analytica 5.0|5.0]])'' The name of the operating system that your Excel instance is running on, as reported by Excel.
|-
| <code>"ReadOnly"</code> || True (1) if the file is saved as Readonly.
|-
| <code>"Saved"</code> || False (0) if it has unsaved changes.
|-
| <code>"SelectedRange"</code> || The currently selected Range.
|-
| <code>"SelectedRangeR1C1"</code> || The currently selected Range specified by row and column number.
|-
| <code>"Sheets"</code> || A list of the names of all the worksheets
|-
| <code>"ThousandsSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character Excel uses to group thousands when displaying a large number. In English-speaking countries this is ',' (a comma). For example, in the number <code>1,234,456.78</code>, groups of thousands are separated by commas.
|-
| <code>"Title"</code> || The title of the spreadsheet
|-
| <code>"URL"</code> || ''([[Analytica 7.2|7.2]])'' The link of a workbook opened from Google Sheets or Google Drive. Null for other workbooks.
|-
| <code>"UseSystemSeparators"</code> || ''([[Analytica 5.0|5.0]])'' True when Excel uses <code>"DecimalSeparator"</code> and <code>"ThousandsSeparator"</code> for displaying numbers.
|-
| <code>"Version"</code> || ''([[Analytica 5.0|5.0]])'' The version number (text) for the installed release of Excel. Excel 2010 is "14.0", Excel 2013 is "15.0" and Excel 2016 is "16.0".
|-
| <code>"Visible"</code> || True when the Excel UI is visible.
|} The items above marked with ''([[Analytica 5.0|5.0]])'' require [[Analytica 5.0]] or better; those marked ''([[Analytica 7.2|7.2]])'' require [[Analytica 7.2]].

== History==

Functions for reading cells from Excel were first present in Analytica 4.1 with functions named [[OpenExcelFile]], [[WorksheetCell]] and [[WorksheetRange]], although these were labelled as ''experimental'', and the present functions were not officially available until 4.2.0. The old names are now deprecated, replaced with [[SpreadsheetOpen]], [[SpreadsheetCell]] and [[SpreadsheetRange]]. The old functions still work, but may be removed in future Analytica releases. The parameters have changed slightly from [[WorksheetRange]] to [[SpreadsheetRange]], with the sheet parameter moved from being the second to being the last parameter and now optional -- no longer required for named ranges or ranges of the form <code>"Sheet1!A1:Z99"</code>.

[[SpreadsheetInfo]] was introduced in [[Analytica 4.5]]. These options to [[SpreadsheetInfo]] were added in [[Analytica 5.0]]: "Version", "CalculationVersion", "Excel.CalculationVersion", "UseSystemSeparators", "DecimalSeparator", "ThousandsSeparator", and "CalculationState".

The color options for «what» incorrectly returned numbers in 0x00bbggrr order, instead of 0x00rrggbb order prior to [[Analytica 5.0]]. (This was a bug -- the documentation stated it should be 0x00rrggbb). Various options to the «what» parameter of [[SpreadsheetCell]] and [[SpreadsheetRange]] have appeared at different releases. The options <code>'HorizontalAlignment'</code> and <code>'VerticalAlignment'</code> appeared in [[Analytica 5.0]]. Options <code>'Address'</code>, <code>'AddressR1C1'</code>, <code>'Sheet'</code> and <code>'RangeName'</code> appeared in [[Analytica 4.6]]. The remaining options appeared in [[Analytica 4.4]], except for <code>'Value'</code>, <code>'NumericValue'</code>, <code>'Formula'</code>' and <code>'RelativeFormula'</code>, which appeared when the «what» parameter was introduced in [[Analytica 4.3]].

{{Release|1=7.2|2=|3=The <code>'GoogleSheets'</code> «backend» of [[SpreadsheetOpen]] (Google Sheets spreadsheets and Excel workbooks stored in Google Drive, opened from their link), and the "Backend", "URL" and "Account" items of [[SpreadsheetInfo]], were added in [[Analytica 7.2]].}}

== See Also ==

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[media:Spreadsheet Helper lib.ana|Spreadsheet Helper lib.ana]]
* [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]]
* [[Media:Functions for Reading Excel Worksheets.ana|Reading Excel Worksheets.ana]]
* [[Read and Write Spreadsheets]]
* [[Excel spreadsheets read and write]]
* [[Functions to Write Data to Excel Worksheets]] -- [[SpreadsheetSetCell]], [[SpreadsheetSetRange]] and [[SpreadsheetSave]]
* {{Release|1=7.2|2=|3=[[Using your own Google OAuth client]] -- connecting to Google Sheets through your own Google Cloud registration}}
* {{Release|1=7.2|2=|3=[[Using a Google service account]] -- opening a Google Sheet with no browser and nobody present}}
* You can also use [[DbQuery| ODBC]] -- a standard database access method to read from Excel spreadsheets.
* [[SuppressExcelAlerts]]
* [[Excel to Analytica Translation]]
* [[Excel to Analytica Mappings]]
* [[ReadTextFile]]
* [[ReadCsvFile]]
* You can use these functions from [[Excel Functions from ADE| ADE]].
* These spreadsheet functions above are more flexible than [[OLE linking]] which is also available.
* [[OLE linking]] </div>

WriteTextFile

2026-09-24T19:17:52Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:System Functions]]
[[category:Database Functions]]
[[category:File system functions]]
[[Category:Doc Status D]] 

{{ReleaseBar}}

== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding{{Release|6.0||, download}}{{Release|7.1||, extensionFilter}}'') ==

Write «text» value to a file with name «filename».

=== Optional parameters ===

«append»: Default <code>False</code>. If the file exists and «append» is <code>True</code>, it appends the text to the end of the file. If it doesn't exist and «warn» is <code>True</code> , it asks whether to create the file.

«warn»: Default <code>True</code>. If «warn» is <code>False</code>, it suppresses the warning that the file already exists when «append» is false or that it does not exist when «append» is True.

«showDialog»: Default <code>Undefined</code> -- i.e. it shows a file browser dialog only if the indicated filename is a folder, a read-only file, or if it exists and «warn» is <code>True</code>, or if it does not exist and «append» is <code>True</code>. When «showDialog» is <code>True</code>, it always opens a dialog before with file name as the default to let the user change file name or folder. When <code>False</code>, it never shows a dialog but may generate an error when trying to overwrite an existing file with «append» False.

«sep»: (Default is a new line.) Character to use as a separator between elements when «text» is an array.

«encoding» (Default <code>"ANSI"</code>.) Specifies how to encode characters in the file:
* <code>"ANSI"</code> : One byte per character, [http://en.wikipedia.org/wiki/8859 ISO-8859-1]. Extended characters (above ascii 255) are written as ?.
* <code>"UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] with a [http://en.wikipedia.org/wiki/Byte_order_mark byte order mark] ([http://en.wikipedia.org/wiki/Byte_order_mark BOM]). The UTF-8 encoding uses one byte for comman characters, and 2-3 bytes for characters with ascii values above 127.
*<code> "-UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] without a BOM.
* <code>"UTF-16"</code> : Two bytes per character, big endian, with BOM.
* <code>"UTF-16le"</code> : Two bytes per character, little endian, with BOM.

{{Release|6.0||
«download»: This is only used when running the model in [[ACP]]. When set to <code>True</code>, the «text» is downloaded onto the end-user's computer as a text file with the given «filename». }}

{{Release|1=7.1|2=|3=
«extensionFilter»: (Optional) Overrides the file types offered in the file-selector dialog. Specify the filter(s) as a text in any of these forms:
* ''Display form'' — one or more filters separated by semicolons, each a description with its patterns in parentheses, e.g. <code>"Text Files (*.txt); CSV Files (*.csv); All Files (*.*)"</code>.
* ''A list of'' <code>"Description{{!}}patterns"</code> ''filters'' (description first, patterns separated by <code>;</code>), e.g. <code>["Text files{{!}}*.txt;*.csv", "All files{{!}}*.*"]</code>.
* ''Just patterns'', e.g. <code>"*.txt;*.csv"</code> (a description is generated automatically).
An <code>"All files (*.*)"</code> entry is appended automatically unless your list already includes one. When omitted, the default file types are shown.
}}

==History==
Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].

«encoding» parameter introduced in [[Analytica 4.5]].

«download» parameter introduced in [[Analytica 6.0]].

«extensionFilter» parameter introduced in [[Analytica 7.1]].

== See also ==
* [[Custom file system providers]] -- paths such as <code>repo://Sales/Q3</code> in a file store
* [[ReadTextFile]]
* [[Read and write text files]]
* [[MakeCSV]]
* [[MakeJSON]]
* [[Text functions]]
* [[WriteBinaryFile]]
* [[CurrentDataFolder]]
* [[Model File Character Encoding]]
* [[Files and Editing]]

FileSystemDelete

2026-09-24T19:17:51Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:File system functions]]

''New to [[Analytica 6.0]]''

''Requires {{Analytica Developer}} edition or better.''

== FileSystemDelete( filepath'', deleteReadOnly, deleteNonEmptyFolder'' ) ==

Deletes a file or folder.

There are other ways to delete a file or folder by using [[RunConsoleProcess]] or [[COM Integration|system COM objects]], but these other methods may be unavailable for security reasons when you run your model on the public [https://Acp.analytica.com Analytica Cloud Platform (ACP)] server, whereas this one is available and secure on ACP.

=== Parameters ===

* «filepath»: The file or folder to be deleted. When this is a relative path, it is interpreted relative to [[CurrentDataFolder]]. Wildcards are not accepted.

* «deleteReadOnly» (Optional, default False): If omited or False, files with the read-only attribute set will not be deleted.

* «deleteNonEmptyFolder» (Optional, default False): If omited or False, a non-empty folder will not be deleted.

=== Return value ===

The (previous) full absolute path to the file or folder that was removed.

== Notes ==
• Requires {{Analytica Developer}} edition or better.
• Can be used (securely) on Analytica Cloud Platform (ACP). You must have write access to the folder containing «filepath», i.e., only in your own project folder.

== See Also ==
* [[Custom file system providers]] -- paths such as <code>repo://Sales/Q3</code> in a file store
* [[:category:File system functions|]
* [[FileFullPath]]
* [[FileSystemMove]], [[FileSystemCopy]]
* [[FileSystemListing]]

FileSystemMove

2026-09-24T19:17:51Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:File system functions]]

''New to [[Analytica 6.0]]''

''Requires [[Analytica Enterprise]] edition or better.''

== FileSystemMove( source, dest ) ==

Renames a file or folder, moves a file to a new location, or moves a folder and all its contents to a new location.

=== Parameters ===

* «source»: A file path to an existing file or folder to be moved or renamed. If this is a relative path, it is interpreted relative to the CurrentDataFolder(). Wildcards are not accepted. If «source» is a folder, then the entire contents will be moved.

* «dest»: The destination name. If this is a relative path, it is interpreted relative to the CurrentDataFolder(). When moving a folder, suffix «dest» with '\' if you want to copy into «toPath» and don't suffix with '\' if you want «dest» to be the final name. See the examples below.

===Return value===
The full path of the file or folder after it has been moved.

==Examples==
* When both «source» and «dest» are filenames but in different folders, the file is moved AND renamed.
*:<code>[[FileSystemMove]]( "C:\MyTemplates\blank.xls", "results.xlsx" )</code>
*::==> Moves it to your [[CurrentDataFolder]], same as where your model resides unless you've changed it.

* When «source» is a file and «dest» is an existing folder, it moves it into the «dest» folder.
*:<code>[[FileSystemMove]]( "C:\MyModels\cashFlow.ana", "D:\Backups\Models" )</code>
*:==> moves to <code>"C:\Backups\Models\cashFlow.ana"</code>

* When «source» is a folder and «dest» ends with \, then it moved it to inside the «dest» folder.
*:[[FileSystemMove]]( "C:\MyModels", "D:\Backups\" )</code>
*:==> moves the entire folder tree to <code>"D:\Backups\MyModels"</code>

* When «source» is a folder and «dest» does not end with \, then «dest» is the name of the folder after it is moved.
*:[[FileSystemMove]]( "C:\MyModels", "D:\Models2" )</code>
*:==> The folder <code>"D:\Models2"</code> is the resulting folder.

== Notes==
* Requires Analytica Enterprise edition or better.
* Can be used (securely) on Analytica Cloud Platform (ACP). You must have read access to the «source» folder and write access to the «dest» folder.

==See Also==
* [[Custom file system providers]] -- paths such as <code>repo://Sales/Q3</code> in a file store
* [[:category:File system functions|File system functions]]
* [[FileSystemCopy]]
* [[FileFullPath]]
* [[FileSystemDelete]], [[FileSystemListing]]
* [[FileSystemNewFolder]]

FileSystemCopy

2026-09-24T19:17:51Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:File system functions]]

''New to [[Analytica 6.0]]''

''Requires {{Analytica Developer}} edition or better.''

== FileSystemCopy( source, dest'', replace, copyLinks'' ) ==

Copies a file, or recursively copies a folder and its contents.

Note: There are other ways to copy files or folders by using [[RunConsoleProcess]] or [[COM Integration|system COM objects]], but these other methods may be unavailable for security reasons when you run your model on the public [https://Acp.analytica.com Analytica Cloud Platform (ACP)] server, whereas this one is available and secure on ACP.

=== Parameters:===

* «source»: A file path to an existing file or folder to be copied. If this is a relative path, it is interpreted relative to the [[CurrentDataFolder]]. Wildcards are not accepted. If the «source» is a folder, then the entire contents will be recursively copied.

* «dest»: Where the file or folder should be copied to. If this is a relative path, it is interpreted relative to the [[CurrentDataFolder]]. When copying a folder, suffix «dest» with '\' if you want to copy into «dest» and don't suffix with '\' if you want «dest» to be the final name. See the examples below.

* «replace»: (optional, default False) Set to True to replace (without asking) if the destination file exists. False to throw an error if a destination file or folder exists.

* «copyLinks»: (optional, default false): Set to true if you want symbolic links to be copied.

=== Return value: ===
The number of files copied or new folders created.

== Examples ==
*Both «source» and «dest» can be filenames.
*:<code>[[FileSystemCopy]]( "C:\MyTemplates\blank.xls", "results.xlsx" )</code>
*:==> Copies to your [[CurrentDataFolder]], same as where your model resides unless you've changed it.

* When «source» is a file and «dest» is an existing folder, it makes a copy with the same filename in the «dest» folder.
*:<code>[[FileSystemCopy]]( "C:\MyModels\cashFlow.ana", "D:\Backups\Models", replace:true )</code>
*:==> copies to <code>"C:\Backups\Models\cashFlow.ana"</code>

* When «source» is a folder and «dest» ends with \, then it makes a copy as the same name as «source» inside the «dest» folder.
*:<code>[[FileSystemCopy]]( "C:\MyModels", "D:\Backups\", replace:true )</code>
*:==> copies the entire folder tree to <code>"D:\Backups\MyModels"</code>

* When «source» is a folder and «dest» does not end with \, then «dest» is the name of the copied folder.
*:<code>[[FileSystemCopy]]( "C:\MyModels", "D:\Models2" )</code>
*:==> The folder "D:\Models2" becomes a replica of "C:\MyModels"

==Notes==
* Requires {{Analytica Developer}} edition or better.
* Can be used (securely) on Analytica Cloud Platform (ACP). You must have read access to the «source» folder and write access to the «dest» folder.

== See Also ==
* [[Custom file system providers]] -- paths such as <code>repo://Sales/Q3</code> in a file store
* [[:category:File system functions|File system functions]]
* [[FileSystemMove]]
* [[FileFullPath]]
* [[FileSystemListing]]
* [[FileSystemDelete]]

FileSystemNewFolder

2026-09-24T19:17:51Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:File system functions]]

''New to [[Analytica 6.0]]''

''Requires {{Analytica Developer}} edition or better.''

== FileSystemNewFolder( name, parentFolder ) ==

Creates a new folder with the name «name», if it doesn't already exist, and returns its full path.

The optional «parentFolder» specifies the location where the new folder is created. When this is specified, the new folder must be located in the «parentFolder».

When «parentFolder» is omitted and «name» is not a full absolute file path, then «name» is interpreted relative to the [[CurrentDataFolder]].

«name» can be a full path to the folder. All folders along the path that don't already exist are created.

== Examples ==
* <code>[[FileSystemNewFolder]]( "c:\DataFeeds\ISO" )</code>
*:This might create two nested folders: <code>"C:\DataFeeds"</code> and <code>"C:\DataFeeds\ISO"</code>

* <code>[[FileSystemNewFolder]]( "MyData" )</code>
*:Creates a folder named <code>"MyData"</code> inside the ]]CurrentDataFolder]]. Returns the full path.

* <code>[[FileSystemNewFolder]]( "Data", "D:\Documents\Models" )</code>
*:Creates the folder <code>"D:\Documents\Models\Data"</code>

== Use in ACP ==
There are other ways to create a new folder using [[RunConsoleProcess]] or [[COM Integration|system COM objects]], but these other methods may be unavailable for security reasons when you run your model on the public [https://Acp.analytica.com Analytica Cloud Platform (ACP)] server, whereas this one is available and secure on ACP.

In general, you will only be able to create a new folder using this function inside your model's own project directory.

== See Also ==
* [[Custom file system providers]] -- paths such as <code>repo://Sales/Q3</code> in a file store
* [[:category:File system functions|File system functions]]
* [[FileSystemListing]]
* [[FileFullPath]]

Analytica Command Line

2026-09-24T19:17:50Z

Lchrisman: Custom file system providers: URI paths now supported here (write/file-management/spreadsheet support)

[[category:File Commands]]
[[Category:Analytica User Guide]]

{{ReleaseBar}}

The desktop Analytica.exe process is launched with a command line having the format:

Analytica.exe [options] [filename]

The brackets mean that these are optional. When ''filename'' has one or more spaces, you need to put double quotes around the filename. Or, you can put double quotes around the ''filename'' even if it doesn't have spaces. The ''filename'' will usually have the extension *.ana. When no filename is specified, Analytica launches to the intro screen. When a filename is specified, it loads that model file.

== Options ==

Each option can be prefixed either with a forward slash, <code>/</code>, or with a minus, <code>-</code>. Option values appear after a colon. There can be no spaces within the option or its value. When an option value contains a space, the option value must be quoted using double quotes.

{{Release|1=7.2|2=|3=As of [[Analytica 7.2]], an option may also be prefixed with a double minus, <code>--</code>, and an option value may be introduced by an equal sign, <code>=</code>, in place of the colon. So <code>/nosplash</code>, <code>-nosplash</code> and <code>--nosplash</code> are all the same option, and <code>/mcp:8080</code> and <code>--mcp=8080</code> are the same option with the same value. This makes the spellings that are conventional for Chromium and for command lines on other operating systems work as expected.}}

* <code>/rlmDiag:''filename''</code>: Writes diagnostic information about licenses to ''filename''. This is very useful if you are encountering problems with a license that you believe has been activated, but is not working. After launching Analytica with this option, exit Analytica and either review the log file in a text editor, or email the diagnostic file to support@lumina.com for assistance. The diagnostic file logs the information about licenses that it finds on your computer, and hence is very useful for debugging license problems.
*: Example usage: <code>Analytica.exe /rlmDiag:"c:\Temp\rlmDiag.log"</code>

* <code>/roam:''days''</code>: Specifies the number of days to roam a floating license. Or, if ''days'' is -1, it releases a roamed license. See [[License Roaming]].
*: Example usage: <code>Analytica.exe /roam:7</code>

* <code>/lic:''licenseName''</code>: Uses the specified license name without changing which license is selected by default. The license must already be activated (i.e., the license must be in your <code>C:\ProgramData\Lumina\Licenses</code> folder).
*:Example: <code>Analytica.exe /lic:analytica_optimizer_761_2</code>

* <code>/rlm:''server''</code>: Specifies the server name (or port@serverName) that is running a Reprise License Manager with the desired centrally managed (e.g., floating) license.

* <code>/eval:''expression''</code>: (new to [[Analytica 6.0]]). Specifies an Analytica expression that is evaluated immediately after the model file that is specified on the command line finishes loading. The evaluating occurs after any proactively evaluated variables or buttons in the model. It does not dirty the model. The expression can include global variable assignments, and button identifiers. You will almost certainly want to include double quotes around the expression, and you need to escape any interior quotes by proceeding the quote with a backslash. {{Release?|1=7.1|2=As of [[Analytica 7.1]], the expression is evaluated even when no ''filename'' appears on the command line; it then runs once the model that Analytica starts up with -- your startup model, or a new untitled model -- has finished loading.|3=The parameter is ignored if ''filename'' is not specified on the command line.}} See [[Running a model in a command line workflow]].

*: Example usage: <code>Analytica.exe /eval:"Claimant=\"JDoe\";Run_Batch;Exit" "Claim analysis.ana"</code>
*: In this example, <code>Claimant</code> is the identifier of an input variable in the model and <code>Run_batch</code> and <code>Exit</code> are names of a buttons in the model.

{{Release|1=7.2|2=|3=
* <code>/evalThenExit:''expression''</code>: (new to [[Analytica 7.2]]) The same as <code>/eval:</code>, except that Analytica exits as soon as ''expression'' has finished, without asking whether to save changes. This is almost always what you want in a [[Running a model in a command line workflow|command line workflow]].
*: Example usage: <code>Analytica.exe /evalThenExit:"Claimant=\"JDoe\";Run_Batch" "Claim analysis.ana"</code>
*: Before 7.2, you had to write the exit into the expression yourself, as <code>/eval:"''expression'';EvaluateScript('[[User Interface Typescript Commands#Bye|Bye]] -')"</code>. That was awkward and easy to leave out -- and when it was left out, the batch run did its work and then sat at an idle Analytica window forever, waiting for a person who was never coming.
*: If ''expression'' exits on its own -- because it runs <code>Bye</code>, or presses a button that does -- that simply happens first, and this option then has nothing left to do.
*: If ''expression'' fails, the error dialog still appears and waits to be dismissed before Analytica exits. Add <code>[[Analytica Command Line/Automation|/Automation]]</code> when the run must not stop for a dialog under any circumstances.
*: <code>/eval:</code> and <code>/evalThenExit:</code> may both appear on the same command line, in which case the <code>/eval:</code> expression is evaluated first.
}}

* <code>/comment:''text''</code>: (new to [[Analytica 6.0]]) The ''text'' is a comment that is ignored by Analytica. In one example usage, ACP3 adds a comment to each spawned processes to differentiate them in task manager.

* <code>/NoSplash</code>: (new to [[Analytica 6.0]]) Don't show the splash screen at startup (which normally displays for 3 seconds).

* <code>/mcp:«port»</code>: (new to [[Analytica 7.0]]) Enable Analytica as [[MCP server in Analytica|an MCP server]] (a protocol that allows A.I. language models to call functions in your model). [[UDF]]s that contain <code>@mcpTool</code> in their description are exposed as functions that the external A.I. client can call.

* <code>/lang:«code»</code> (new to [[Analytica 7.1]]) Specifies the User Interface language for Analytica (for menus, dialogs, error messages, built-in function descriptions, etc.). «code» is a language code such as <code>'en'</code> (for English), <code>'es'</code> (for Spanish), etc. The language is only used when the resource files exist for that language in
*:<code>«Analytica install folder»\Resources\«code»\</code>
*: The command line overrides the registry setting <code>Language</code> (if present) in the hive
*:<code>HKCU\Software\Lumina Decision Systems\Analytica</code>
*:As of [[Analytica 7.1]], non-English UI options is an experimental feature and not complete.

The remaining options exist for internal purposes and aren't generally used by end-users:
* <code>/embedding</code>: The Windows operating system uses this parameter when launching Analytica as a OLE-link server. Not used by end-users. Causes Analytica to launch quietly (without a GUI), load an indicated model, and exposes key OLE interfaces to Windows enabling an external application to complete the link to the model's data.

* <code>/solverDevLic</code>: This parameter is sometimes used by Analytica developers, but not generally by end-users. It indicates that the licenses from [https://solver.com Frontline Systems] found in the <code>Solver.lic</code> file are developer licenses rather than runtime licenses.

* <code>/forcerelease</code>: This parameter is used by Analytica quality assurance engineers during beta testing periods. It causes a beta release to behave like a final release build with regard to licensing.

*<code>/config:''filename''</code>: This is an option used by ACP3 (by Suan.exe) and not in Desktop Analytica. The specified config file contains settings that define the ACP3 server configuration.

{{Release|1=7.2|2=|3=
* <code>/remote-debugging-port:«port»</code>: (new to [[Analytica 7.2]]) Exposes the Chrome DevTools protocol (remote debugging) endpoint of Analytica's embedded Chromium (CEF) browser windows on <code>127.0.0.1:«port»</code>, so that an external tool — a benchmark driver, Claude Code, Puppeteer, or Chrome's <code>chrome://inspect</code> page — can inspect and drive HTML-based windows such as the Assista chat window, HTML dialogs, and windows created with the <code>CefWindow</code> function. The Chromium spelling <code>--remote-debugging-port=«port»</code> is also accepted. Use a «port» of 0 to have a free (ephemeral) port picked automatically. Valid values are 0 or 1024 through 65535. The endpoint listens only on 127.0.0.1, and enabling it is per-process (all CEF windows of the process share one endpoint, with one DevTools target per window).
*: After launch, the process reports the outcome in <code>%LOCALAPPDATA%\Lumina\Analytica\CEF\«pid»\RemoteDebug.json</code>, where «pid» is the process id of the launched Analytica.exe. On success this contains <code>"status":"listening"</code> and the actual port; when the requested port is already in use by another process, or CEF fails to initialize, it contains <code>"status":"failed"</code> with a reason, and a warning dialog is also shown. A tool that launches Analytica.exe with this option should read this file rather than connecting blindly, so that it cannot be fooled into talking to some other process that owns the port.
*: While remote debugging is enabled, each page in a CEF window exposes the JavaScript global <code>window.anaCefWindow</code> with fields <code>pid</code>, <code>handle</code>, <code>kind</code> and <code>title</code>, identifying which window a DevTools target belongs to. The <code>handle</code> matches the handle of the corresponding <code>CefWindow</code> object in the model.

* <code>/remote-allow-origins:«origins»</code>: (new to [[Analytica 7.2]]) A comma-separated list of origins (or <code>*</code>) allowed to connect to the remote-debugging endpoint from a web page. This is only needed when the DevTools client is itself a web page, which sends an HTTP Origin header that Chromium rejects by default. Ordinary clients (Python or Node scripts, Puppeteer, <code>chrome://inspect</code>) send no Origin header and connect without this option. The Chromium spelling <code>--remote-allow-origins=«origins»</code> is also accepted.
}}
{{Release|1=7.2|2=|3=
* <code>/lib:''filename''</code>: (new to [[Analytica 7.2]]) Loads the Analytica library in ''filename'' into the <code>SysLib_Customizations</code> system module, before the model named on the command line is opened. The library is then present no matter which model is loaded, and it stays loaded as models are closed and opened during the session. The option can be repeated to load several libraries. They load in the order given, all of them before the model.
*: Example usage: <code>Analytica.exe /lib:"W:\Analytica\Libraries\Multivariate Distributions.ana" MyModel.ana</code>
*: A relative ''filename'' is looked for first in the directory that the process was launched from, then in the directories on the <code>AddLibraryDir</code> library search path, then in the Analytica installation folder, and finally in the preferences folder. Path substitutions such as <code>%appdata%</code> and <code>%installdir%</code> are expanded.
*: Each library loaded this way is its own namespace. Since <code>SysLib_Customizations</code> is a private namespace, the library is not in namespace scope for the user's model. A model that wants to use one of these libraries must name it in its [[NamespaceImports]] attribute.
*: When the file is not found, or when it fails to load, a warning dialog names the file and Analytica continues to start up without it.
*: Uses for this include loading an [[MCP server in Analytica]] that works with whatever model is subsequently loaded, a benchmark driver, or a library that adds toolbar buttons or menu items.
}}

{{Release|1=7.2|2=|3=
* <code>/stores:''filename''</code>: (new to [[Analytica 7.2]]) Names the <code>FileProviders.config</code> file that declares the [[Custom file system providers|custom file system providers]] this process should use. A file provider makes a URI-style path such as <code>repo://Sales/Q3.csv</code> usable anywhere Analytica accepts a file name -- opening a model, [[ReadTextFile]], [[FileSystemListing]], and so on -- with the <code>repo</code> prefix served by an HTTP storage service that you configure, or write yourself.
*: Example usage: <code>Analytica.exe /stores:"C:\ACME\FileProviders.config" MyModel.ana</code>
*: A relative ''filename'' is resolved against the directory that the process was launched from.
*: This option '''overrides''' the other places the file is otherwise looked for -- the <code>ANALYTICA_FILE_PROVIDERS_CONFIG</code> environment variable, the <code>FileProvidersConfig</code> registry value, and a <code>FileProviders.config</code> sitting in the same folder as the engine binary -- so it is mainly a deployment and debugging convenience. The registry value is the usual way to configure stores, and, with the environment variable, it is the only way to do it for [[ADE]] and ADEW, which have no command line of their own.
*: The configuration is read once, while the engine initializes, so changing it means restarting the process. When the file named is not there, no providers are registered.
*: The same option, with the same meaning, is accepted by <code>Suan.exe</code> and by <code>Amp.exe</code>.
*: Requires the {{Analytica Developer}} edition or better. For what to put in the file, and for the HTTP API a storage service implements, see '''[[Custom file system providers]]'''.
}}

{{Release|1=7.2|2=|3=
* <code>/Automation</code>: (new to [[Analytica 7.2]]) Runs Analytica in ''automation mode'', in which every modal dialog that would otherwise block is answered automatically, so that an unattended run never stops waiting for a person. Each dialog is answered either by a built-in default, or by a handler function that the model or a library registers with [[RegisterAutomationModalHandler]]. This is intended for unattended and agent-driven runs, such as a benchmark driver, an automated QA run, or a session driven by an AI coding agent through the [[MCP server in Analytica]].
*: This is '''not''' a headless mode. The user interface, diagram windows, HTML dialogs, and Assista all remain fully alive and usable; only the blocking dialogs are answered for you. The splash screen is suppressed, as with <code>/nosplash</code>, and no recovery file is written, as with <code>/Autosave=0</code> (give <code>/Autosave=1</code> explicitly to keep auto-recovery on).
*: Some built-in defaults are deliberately conservative so that an unattended run cannot damage the model it is testing. In particular, "Save changes?" is answered '''No''', so the model file on disk is never written when the process exits. File open and save prompts fail rather than choosing a file, unless a registered handler supplies a path.
*: For the full list of defaults, how to write and register a handler, and worked examples of driving Analytica this way, see '''[[Analytica Command Line/Automation]]'''.
*: Example usage: <code>Analytica.exe /Automation /lib:BenchmarkDriver.ana MyModel.ana</code>

* <code>/AutomationTrace:''filename''</code>: (new to [[Analytica 7.2]]) Writes a log of every modal dialog to ''filename'', in JSON Lines format (one JSON object per line). Each dialog record names the kind of dialog, its caption and body text, the buttons it offered, the answer that was given, and where that answer came from. Records are appended, so a driver can pre-create the file and tail it while the run proceeds, and each record carries the process id so that concurrent runs remain distinguishable.
*: Used together with <code>/Automation</code>, this records what automation answered. Used '''without''' <code>/Automation</code>, it is an ''observe mode'': dialogs appear and behave completely normally, and the log records what the user actually chose. This is a convenient way to inventory which dialogs a scenario poses before you automate it.
*: A relative ''filename'' is resolved against the directory the process was launched from. If the file cannot be opened, Analytica starts normally and simply produces no log.
*: Example usage: <code>Analytica.exe /Automation /AutomationTrace:C:\Temp\run1.jsonl MyModel.ana</code>
}}

{{Release|1=7.2|2=|3=
These two options place the main Analytica application window explicitly, instead of using the size and position that Analytica saved when it last exited. They are intended for benchmark automation and automated QA, where the window needs to be the same from one run to the next, or needs to be somewhere predictable.

* <code>/WindowSize:«width»,«height»</code>: (new to [[Analytica 7.2]]) Sets the size of the main application window, in screen pixels.
*: Example usage: <code>Analytica.exe /WindowSize:1000,600</code>

* <code>/WindowXY:«x»,«y»</code>: (new to [[Analytica 7.2]]) Sets the position of the top left corner of the main application window, in screen coordinates. On a computer with more than one monitor, these coordinates can be negative, or larger than the size of the primary monitor, to place the window on another monitor.
*: Example usage: <code>Analytica.exe /WindowSize:1000,600 /WindowXY:-1000,100</code>

Either option can be used without the other. The one you leave out keeps the value that was saved when Analytica last exited.

The window is placed exactly where you ask for it. Unlike a position restored from a previous session, it is not nudged back onto a monitor, so a window that falls partly or entirely off screen stays where you put it. These options also take precedence over a maximized state saved from the previous session, and over the ''Run: Maximized'' setting of a Windows shortcut, so that the size you ask for is never ignored.

The geometry given on the command line is '''not''' saved back to the registry when Analytica exits. An automated run that uses these options therefore leaves the window size and position of your own interactive sessions undisturbed.

The size is that of the visible window frame. Windows surrounds that frame with an invisible drop shadow, so a script that measures the window using <code>GetWindowRect</code> sees a few extra pixels on each side, while <code>DwmGetWindowAttribute</code> with <code>DWMWA_EXTENDED_FRAME_BOUNDS</code> reports exactly the size that was requested.

A value that is not two whole numbers, or a width or height that is not positive, produces the ''Unrecognized command line parameter'' warning and that option is ignored.

* <code>/Autosave=0</code> or <code>/Autosave=1</code>: (new to [[Analytica 7.2]]) Turns the ''Maintain recovery info'' preference off or on for this process only, without changing the stored preference. That preference controls the incremental autosave that lets Analytica offer to recover unsaved changes after a crash. With <code>/Autosave=0</code>, no recovery file is written while the process runs, so if the process is killed rather than closed, the next launch does not stop at the "recover unsaved changes?" dialog. With <code>/Autosave=1</code>, recovery information is maintained for the session even when the preference is off (in editions that support auto-recovery). A bare <code>/Autosave</code> means <code>/Autosave=1</code>; the spellings <code>/Autosave:0</code> and <code>--autosave=0</code> are also accepted.
*: Example usage: <code>Analytica.exe /Autosave=0 MyModel.ana</code>
*: When <code>/Automation</code> is given and <code>/Autosave</code> is not, <code>/Autosave=0</code> is implied: an automated run is usually killed rather than closed, and would otherwise leave a recovery record behind for the next interactive launch to ask about. Give <code>/Autosave=1</code> explicitly if an automated run needs auto-recovery on.
*: While the option is in effect, the ''Maintain recovery info'' checkbox in the '''Preferences''' dialog shows the effective state but is disabled. Recovery records left behind by earlier sessions are still offered at startup as usual; the option only controls whether this process writes one. A value other than 0 or 1 produces the ''Unrecognized command line parameter'' warning and the option is ignored.
}}

{{Release|1=7.2|2=|3=
== Command line options for libraries ==

''new in [[Analytica 7.2]]''

An option that begins with a double minus, <code>--</code>, and that is not one of the options listed above, does '''not''' produce the ''Unrecognized command line parameter'' warning. Analytica ignores it and passes it through, so that a library or a model can read it. This lets a library define command line options of its own without having to be built into Analytica. For example:

:<code>Analytica.exe --AssistaURL:<nowiki>"https://aaia.analytica.com/staging"</nowiki> --OpenAssista MyModel.ana</code>

A library reads them with [[GetProcessInfo]]:

:<code>GetProcessInfo("Command line:--AssistaURL") → 'https://aaia.analytica.com/staging'</code>
:<code>GetProcessInfo("Command line:--OpenAssista") → True</code>
:<code>GetProcessInfo("Command line:--NotGiven") → Null</code>
:<code>GetProcessInfo("Command line parameters") → ['--AssistaURL', '--OpenAssista']</code>

The value of such an option is the text that follows its colon or equal sign, and it must be quoted when it contains a space. An option that appears with no value reads as <code>True</code>, and an option that is not on the command line at all reads as <code>Null</code>, so a library can tell those two apart. A value always comes back as text, even when it looks like a number, so use [[ParseNumber]] when you want a number. When the same option appears more than once, the last occurrence is the one reported.

Because Analytica accepts any unrecognized <code>--</code> option silently, a misspelled one is simply ignored rather than reported. <code>GetProcessInfo("Command line parameters")</code> returns the list of <code>--</code> options that actually arrived, which is how a driver or library can check that it was passed what it expected.

The <code>--</code> options are not copied into the file names that Analytica opens, and they are not case-sensitive. When reading one, the leading dashes are optional, so <code>GetProcessInfo("Command line:AssistaURL")</code> finds it as well.

This mechanism is available in Analytica.exe, in ACP (Suan.exe) and in [[ADE]]. In ADE the command line is the one belonging to the host process that loaded ADE, which is the same command line that <code>GetProcessInfo("Command line")</code> reports.
}}

== Accessing the Command line from a model ==

The expression <code>[[GetProcessInfo]]('Command line')</code> returns the command line used to launch the process.

== See also ==
* [[GetProcessInfo]] -- especially <code>GetProcessInfo('Command line')</code>
* [[Running a model in a command line workflow]]
* [[/Automation]]
* [[MCP server in Analytica]]
* [[Custom file system providers]]
* [[Assista]]

Custom file system providers/API spec

2026-09-24T19:16:55Z

Lchrisman: Write and file-management endpoints (PUT/DELETE /files, PUT/DELETE /folders, POST /copy, POST /move); status codes 405/409/412/413/501

[[category:File system functions]]
[[Category:Analytica User Guide]]

{{ReleaseBar}}

''New in [[Analytica 7.2]].'' See also the parent page, [[Custom file system providers]].

__TOC__

== Overview ==

A '''store service''' is an ordinary HTTP service that Analytica calls whenever a model uses a <code>«scheme»://</code> path. A store that is only read from needs three endpoints, and nothing else is required. A store that Analytica may also write to -- saving models, [[WriteTextFile]], [[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]], [[FileSystemDelete]], [[SpreadsheetSave]] -- implements the [[#Write and file-management endpoints|write and file-management endpoints]] as well. No Analytica code is involved, so write the service in whatever language and framework you like, and back it with whatever you like: object storage, a database, a version control system, a document management system, or a REST API of its own.

Analytica is told about the service by one line in <code>FileProviders.config</code>:

:<code>FileStore repo = http://mystore.internal:8080</code>

after which every path beginning <code>repo://</code> becomes a request to that base URL. See [[Custom file system providers]] for the rest of the configuration.

== The endpoints ==

These three serve every read. All endpoints, including the [[#Write and file-management endpoints|write and file-management endpoints]], are relative to the configured base URL, including any path prefix in it. With a base URL of <code>http://mystore.internal:8080/api</code>, the first endpoint is <code>http://mystore.internal:8080/api/files/...</code>.

{| class="wikitable"
! Request !! Purpose !! Success !! Not found
|-
| <code>GET {base}/files/{root}/{path}</code> || Fetch a file || <code>200</code>, with the raw file bytes as the body || <code>404</code>
|-
| <code>HEAD {base}/files/{root}/{path}</code> || Existence check, without transferring the file || <code>200</code> || <code>404</code>
|-
| <code>GET {base}/list/{root}/{path}?recursive=0</code> or <code>?recursive=1</code> || List a folder || <code>200</code>, with a JSON array (see below) || <code>404</code>, taken as an empty listing
|}

<code>{root}/{path}</code> is everything that followed <code>«scheme»://</code> in the model's path. For <code>repo://Sales/2026/Q3.csv</code> the engine requests <code>{base}/files/Sales/2026/Q3.csv</code>. The engine attaches no meaning of its own to <code>{root}</code>: it is simply the first segment. It is there so that one service can host several logical roots -- one per customer, per project or per bucket -- and decide from it which backing store to consult.

The <code>recursive</code> query parameter is sent on every <code>/list</code> request and on no <code>/files</code> request.

A health endpoint is a good idea for your own monitoring, but the engine never calls one and does not require it.

== Path encoding ==

Everything after <code>«scheme»://</code> is the literal path -- unencoded text, as the model author wrote it. Before sending a request, the engine:

# replaces every <code>\</code> with <code>/</code>, and
# percent-encodes every byte that is not in the unreserved set <code>A-Z a-z 0-9 - _ . ~ /</code>.

Your service must percent-decode the path. Because the encoding is applied byte by byte to the UTF-8 form of the name, spaces and non-ASCII characters round-trip correctly: <code>repo://models/Ventas Q3.csv</code> arrives as <code>/files/models/Ventas%20Q3.csv</code>.

The engine refuses a <code>..</code> segment before any request is sent, so a well-behaved client never asks for one. Reject traversal in the service as well; defence in depth is worth the three lines it costs.

== Authentication ==

When a token is configured, with <code>FileStoreToken</code> or <code>FileStoreTokenFile</code>, the engine sends

:<code>Authorization: Bearer «token»</code>

on '''every''' request, to every endpoint. When no token is configured, no <code>Authorization</code> header is sent at all.

Answer <code>401</code> or <code>403</code> when the token is missing, expired or wrong. Analytica turns either one into an error that names the scheme, so the user is told the credentials were rejected rather than that the file is missing.

== How the engine interprets your status codes ==

{| class="wikitable"
! Status !! What the engine does
|-
| <code>200</code> || Success. The body is the file, or the listing.
|-
| <code>404</code> || Not found. Treated as a missing file, with no error text of its own, so the caller reports a missing file in its usual way. On <code>/list</code>, an empty listing.
|-
| <code>401</code> or <code>403</code> || A credentials error naming the scheme: <code>the repo:// file store rejected the credentials (HTTP 401)</code>.
|-
| <code>405</code> || On a write: that store, or that part of it, is read-only. The write fails with <code>the repo:// file store is read-only and refused the write (HTTP 405)</code>.
|-
| <code>409</code>, <code>412</code> || On a write: a conflict -- the destination already exists, a folder is not empty, or a file is in the way of a folder. The function that asked reports it in its own words (for example, that the destination exists and «replace» would allow it).
|-
| <code>413</code> || On a write: the upload is too large. <code>the repo:// file store refused the upload as too large (HTTP 413)</code>.
|-
| <code>501</code> || On a copy or move: the service cannot do it itself. For a single file the engine then does the work with <code>GET</code>, <code>PUT</code> and <code>DELETE</code>; for a folder the operation fails.
|-
| anything else || <code>HTTP «n» from the repo:// file store</code>.
|}

A connection that cannot be made at all, or that times out, is reported as <code>could not reach the repo:// file store (...)</code>, with the transport reason in the parentheses. Neither of those is a status code you control, so return a real status for everything you can: the message the user sees is then about your service rather than about the network.

== The listing response ==

<code>GET {base}/list/{root}/{path}</code> returns a JSON '''array''' of objects, one per entry. A body that does not parse, or that is not a JSON array, is an error.

{| class="wikitable"
! Member !! Type !! Meaning
|-
| <code>name</code> || string || The entry name only, with no path. '''Required''' -- an entry with no <code>name</code>, or whose <code>name</code> is not a string, is skipped.
|-
| <code>isFolder</code> || boolean or number || <code>true</code>, or a non-zero number, for a folder. Absent or false means a file.
|-
| <code>size</code> || number || Size in bytes. Use 0 for folders.
|-
| <code>modified</code> || string || The last-modified time in ISO-8601, UTC, for example <code>"2026-08-14T09:12:03Z"</code>. Omit it when you do not know it.
|}

Members other than these are ignored, so you may return extra information for your own clients.

<pre>
[
{"name": "Q1.csv", "isFolder": false, "size": 20481, "modified": "2026-04-02T17:45:10Z"},
{"name": "Q2.csv", "isFolder": false, "size": 21118, "modified": "2026-07-01T08:03:55Z"},
{"name": "archive", "isFolder": true, "size": 0}
]
</pre>

<code>recursive=1</code> asks for the whole subtree below the folder. When you answer one, <code>name</code> should carry the path '''relative to the folder that was listed''' -- <code>"archive/2025/Q4.csv"</code>, not just <code>"Q4.csv"</code>. That is what lets [[FileSystemListing]] report the sub-path the way it does for a local recursive listing. With <code>recursive=0</code>, return only the immediate children.

The engine, not the service, applies any wildcard the model wrote in the last segment of the path, and applies the «files» and «folders» flags of [[FileSystemListing]]. Return the folder's whole contents and let it do that filtering.

== Write and file-management endpoints ==

These are optional. A store that implements none of them is a read-only store, and every function that would write to it fails cleanly. Implement them when models are to save files, or to create, copy, move and delete them, in your store. Like the read endpoints, they are relative to the base URL, receive the same <code>Authorization</code> header and use the same path encoding.

{| class="wikitable"
! Request !! Purpose !! Answers
|-
| <code>PUT {base}/files/{root}/{path}</code> || Write a whole file. The body is the complete file, with a <code>Content-Length</code>. The header <code>If-None-Match: *</code> means "create only -- do not replace an existing file". || <code>201</code> created · <code>200</code> replaced · <code>412</code> exists (create only) · <code>405</code> read-only · <code>413</code> too large
|-
| <code>DELETE {base}/files/{root}/{path}</code> || Delete a file || <code>200</code> · <code>404</code> · <code>409</code> it is a folder · <code>405</code>
|-
| <code>PUT {base}/folders/{root}/{path}</code> || Create a folder, and any missing parent folders. The body is empty. || <code>201</code> created · <code>200</code> already a folder · <code>409</code> a file is in the way · <code>405</code>
|-
| <code>DELETE {base}/folders/{root}/{path}?recursive=0</code> or <code>?recursive=1</code> || Delete a folder; with <code>recursive=1</code>, everything in it as well || <code>200</code> · <code>404</code> · <code>409</code> not empty (with <code>recursive=0</code>) · <code>405</code>
|-
| <code>POST {base}/copy/{root}/{path}?to={root}/{path}&overwrite=0</code> or <code>&overwrite=1</code> || Copy a file, or a folder and everything in it || <code>201</code> new or <code>200</code> replaced, with the JSON body <code>{"copied": «n»}</code> · <code>404</code> · <code>412</code> the destination exists (with <code>overwrite=0</code>) · <code>409</code> a file/folder clash · <code>405</code> · <code>501</code>
|-
| <code>POST {base}/move/{root}/{path}?to={root}/{path}</code> || Move or rename a file or a folder. Never overwrites. || <code>200</code> · <code>404</code> · <code>412</code> the destination exists · <code>405</code> · <code>501</code>
|}

* The <code>to</code> parameter is percent-encoded exactly like the path.
* A folder is whatever <code>/list</code> reports with <code>isFolder</code>. An object store can represent an empty folder with a placeholder object, provided <code>/list</code> shows the folder and never the placeholder.
* <code>405</code> means read-only, and it may apply to the whole store or to part of it -- one root, say. For a move, the source must be writable as well as the destination; for a copy, only the destination.
* <code>501</code> from <code>/copy</code> or <code>/move</code> means "not possible on the server" -- a copy between two roots that live in different back ends, for example. For a single file, the engine then copies it itself with <code>GET</code> and <code>PUT</code> (and, for a move, <code>DELETE</code>). A move whose source cannot be deleted is undone by deleting the copy it made.
* Refuse <code>..</code> segments, and a bare <code>{root}</code> as the target of any of these requests.

'''Implementers:'''
* Check the write policy '''before''' reading a <code>PUT</code> body, and drain any unread body before sending an early error reply. Some proxies reset the connection otherwise, and the user then sees a network error instead of your status.
* Apply your access rules to '''both''' the path and the <code>to</code> path of a copy or move.
* A service that predates these endpoints leaves the functions that need them failing with <code>the repo:// file store does not support this operation (the store service may need to be updated)</code>.

== Sizes, timeouts and cancellation ==

* The engine aborts a fetch as soon as it can see that the transfer exceeds <code>FileStoreMaxMB</code> (256 MB by default), whether it learns that from <code>Content-Length</code> or from the bytes received so far. Send a <code>Content-Length</code> where you can, so that an oversized file is refused before it is transferred rather than during.
* The connect timeout is 5 seconds and is not configurable. The read timeout is <code>FileStoreTimeoutS</code>, 60 seconds by default. A service that has slow work to do before it can produce a file should still start responding promptly.
* Streaming or chunking a large body is fine, and is preferable to buffering the whole thing in the service.
* A user can cancel a transfer that is in progress. From the service's point of view that looks like the client closing the connection part-way through a response, which the service should handle gracefully.

== HTTP only ==

The engine's HTTP client has no TLS support, so the base URL must be <code>http://</code>; an <code>https://</code> URL is refused when the provider is registered. Bind the service to <code>127.0.0.1</code>, or to a private network or cluster network only. The bearer token and the file bytes are both in the clear over that hop. See [[Custom file system providers#Security]].

== An illustrative skeleton ==

The smallest thing that works, in Python, serving a couple of directory trees. It is here to show the shape of the three read endpoints and of the listing JSON; it implements none of the write endpoints, and it is not something to deploy. It uses Python's single-threaded development server, and its traversal checking is only the obvious one.

<pre>
import datetime, json, os, urllib.parse
from http.server import BaseHTTPRequestHandler, HTTPServer

ROOTS = {"Sales": "/srv/data/sales", "models": "/srv/data/models"}
TOKEN = "«bearer-token»"

def resolve(rest): # "Sales/2026/Q3.csv" -> a local path
parts = [p for p in urllib.parse.unquote(rest).split("/") if p]
if not parts or ".." in parts or parts[0] not in ROOTS:
return None
return os.path.join(ROOTS[parts[0]], *parts[1:])

def entry(dirpath, name, rel):
full = os.path.join(dirpath, name)
isdir = os.path.isdir(full)
when = datetime.datetime.utcfromtimestamp(os.path.getmtime(full))
return {"name": rel + name, "isFolder": isdir,
"size": 0 if isdir else os.path.getsize(full),
"modified": when.strftime("%Y-%m-%dT%H:%M:%SZ")}

class Store(BaseHTTPRequestHandler):
def reply(self, code, body=b"", ctype="application/octet-stream"):
self.send_response(code)
self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(body)))
self.end_headers()
if self.command != "HEAD":
self.wfile.write(body)

def do_GET(self): # HEAD arrives here too
if self.headers.get("Authorization") != "Bearer " + TOKEN:
return self.reply(401)
url = urllib.parse.urlparse(self.path)
kind, _, rest = url.path.lstrip("/").partition("/")
target = resolve(rest)
if target is None:
return self.reply(404)
if kind == "files" and os.path.isfile(target):
with open(target, "rb") as f:
return self.reply(200, f.read())
if kind == "list" and os.path.isdir(target):
recurse = urllib.parse.parse_qs(url.query).get("recursive") == ["1"]
out = []
for dirpath, dirs, files in os.walk(target):
rel = os.path.relpath(dirpath, target).replace(os.sep, "/")
rel = "" if rel == "." else rel + "/"
out += [entry(dirpath, n, rel) for n in dirs + files]
if not recurse:
break
return self.reply(200, json.dumps(out).encode(), "application/json")
return self.reply(404)

do_HEAD = do_GET

HTTPServer(("127.0.0.1", 8080), Store).serve_forever()
</pre>

== Testing your provider ==

# Write a configuration file that points at the service and gives it a scheme: a <code>FileStore repo = http://127.0.0.1:8080</code> line, plus <code>FileStoreToken repo = «bearer-token»</code> if the service wants one.
# Make Analytica find that file -- with <code>/stores:«path»</code>, with the <code>FileProvidersConfig</code> registry value, or by putting it beside the engine binary. See [[Custom file system providers#Where Analytica looks for FileProviders.config|Where Analytica looks for FileProviders.config]].
# Start Analytica and look for the registration line, <code>[FileProviders] repo:// -> http://127.0.0.1:8080</code>. It is written to the engine's typescript: the [[Typescript Window|typescript window]] in Analytica, the log in [[ADE]], ADEW and [[ACP]], and <code>stderr</code> -- the server log -- in [[AMP]]. If it is not there, the configuration file was not found, or the line in it was not understood.
# List the root with <code>[[FileSystemListing]]( "repo://" )</code>. That exercises <code>/list</code> and your JSON shape without needing any file to be readable.
# Read something with <code>[[ReadTextFile]]( "repo://Sales/Q3.csv" )</code>. That exercises <code>/files</code>, including the <code>HEAD</code> existence check that runs first, and <code>[[FileExists]]( "repo://Sales/Q3.csv" )</code> exercises the <code>HEAD</code> endpoint on its own.
# If the service accepts writes, work in a scratch folder: <code>[[WriteTextFile]]( "repo://Sales/scratch/a.txt", "hello" )</code>, then [[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]] and [[FileSystemDelete]] on it, checking each result in the service's own storage rather than through Analytica. Try a write to a location that should be read-only, and expect ''the repo:// file store is read-only and refused the write (HTTP 405)''.
# Then check the failure paths deliberately: a name that does not exist (expect a plain not-found), a bad token (expect a credentials error naming the scheme), and the service stopped (expect ''could not reach the repo:// file store'').

== See Also ==
* '''[[Custom file system providers]]''' -- the parent page: what providers are, and how to configure them
* [[Analytica Command Line]] -- the <code>/stores:«path»</code> option
* [[FileSystemListing]]
* [[ReadTextFile]]
* [[ReadBinaryFile]]
* [[WriteTextFile]]
* [[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]], [[FileSystemDelete]]
* [[SpreadsheetOpen]], [[SpreadsheetSave]]
* [[:Category:File system functions]]

Custom file system providers

2026-09-24T19:16:08Z

Lchrisman: Write support, FileSystemNewFolder/Copy/Move/Delete, SpreadsheetOpen/Save on URI paths; FileStoreTokenEnv; ANALYTICA_FILE_PROVIDERS_CONFIG

[[category:File system functions]]

{{ReleaseBar}}

''New in [[Analytica 7.2]]''

''Requires {{Analytica Developer}} edition or better.'' It is always available in [[ADE|the Analytica Decision Engine]], in [[Analytica Cloud Platform|ACP]], and in [[AMP]] (the [[Analytica MCP Platform]]). In a lesser edition, a <code>«scheme»://</code> path reports that the feature is not available in this edition.

__TOC__

== What a custom file system provider is ==

A '''file provider''' makes a URI-style path

:<code>«scheme»://«root»/«path»</code>

for example <code>repo://Sales/Q3.csv</code>, work anywhere the Analytica engine accepts a file name. That includes opening and saving a model and the modules that model links to or includes; reading and writing files with [[ReadTextFile]], [[ReadBinaryFile]], [[WriteTextFile]] and [[WriteBinaryFile]]; listing and managing files and folders with [[FileSystemListing]], [[FileExists]], [[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]] and [[FileSystemDelete]]; spreadsheets opened with [[SpreadsheetOpen]] and saved with [[SpreadsheetSave]]; path utilities such as [[FileFullPath]] and [[FilePathPart]]; and the internal file-exists tests that model loading uses.

The scheme prefix -- <code>repo</code> in that example -- is '''configuration, not code'''. Providers are registered when the engine starts up, from a plain text file named <code>FileProviders.config</code>, so one deployment can define several prefixes, each backed by a different storage service. Behind each prefix is an HTTP service that speaks a deliberately tiny protocol. You can write that service yourself: see '''[[Custom file system providers/API spec]]'''.

Things this is used for:
* A '''cloud object store''', so that models and data live in a bucket rather than on a file server or on each analyst's own disk.
* A '''document management system''', so that reading a file goes through the same access control and audit trail as every other document in the organization.
* A '''version-controlled model repository''', so that a run can name the exact models and data it used and those names keep meaning the same thing.
* A '''corporate content API''' that already knows where the authoritative copy of a data set lives.

The point of doing it this way is that '''nothing else in the model changes'''. The model author writes

:<code>[[ReadTextFile]]( "repo://Sales/Q3.csv" )</code>

and every other part of the model, and every function that takes a file name, behaves exactly as it does with a local path.

== URI paths ==

* The form is <code>«scheme»://«rest»</code>. A scheme starts with a letter, continues with letters, digits, <code>+</code>, <code>.</code> or <code>-</code>, and is '''at least two characters''' long. The two-character minimum is deliberate: it keeps <code>C://foo</code> a Windows drive path rather than a URI.
* Scheme matching is '''not case-sensitive'''. <code>repo://</code> and <code>Repo://</code> reach the same provider.
* A backslash is accepted inside a URI path and treated as <code>/</code>. So a model at <code>repo://models/Main.ana</code> that includes <code>sub\Child.ana</code> resolves to <code>repo://models/sub/Child.ana</code>.
* <code>.</code> and <code>..</code> segments resolve textually when a relative path is joined onto a URI folder, and <code>..</code> can never pop above <code>«scheme»://«root»</code>. A <code>..</code> segment that would still reach the provider is refused outright.
* A URI is treated as an '''absolute''' path, so relative-path resolution against a model that was opened from a URI works normally.
* The path utilities keep a syntactic URI intact even when no provider is registered for its scheme, so an unknown scheme fails with a clear message instead of being mangled into a Windows path.

== FileProviders.config ==

<code>FileProviders.config</code> is a plain text file with one setting per line. A <code>#</code> starts a comment, blank lines are ignored, and each setting has the form

:<code>«key» «scheme» = «value»</code>

Key names are not case-sensitive.

<pre>
# scheme prefix -> store service. Several FileStore lines define several schemes.
FileStore repo = http://mystore.internal:8080
FileStoreToken repo = «bearer-token» # literal token
FileStoreTokenFile repo = C:\secrets\repo-token # OR read the token from this file
FileStoreTokenEnv repo = REPO_STORE_TOKEN # OR from this environment variable
FileStoreMaxMB repo = 256 # optional fetch size cap (default 256)
FileStoreTimeoutS repo = 60 # optional read timeout (default 60)
</pre>

{| class="wikitable"
! Setting !! Meaning
|-
| <code>FileStore «scheme» = «url»</code> || Declares «scheme» and gives the base URL of the store service that serves it. Required, and it must be the '''first''' line for that scheme.
|-
| <code>FileStoreToken «scheme» = «token»</code> || A bearer token, written literally, that is sent with every request to that store.
|-
| <code>FileStoreTokenFile «scheme» = «path»</code> || Reads the bearer token from this file instead. Surrounding white space in the file is trimmed. It takes precedence over <code>FileStoreToken</code>.
|-
| <code>FileStoreTokenEnv «scheme» = «variable»</code> || Reads the bearer token from this environment variable of the engine's process, and then '''removes the variable from the process's environment''', so that model code -- <code>[[GetProcessInfo]]("env:...")</code>, or a program started with [[RunConsoleProcess]] -- cannot read the token back. Use it when a launcher, such as a container's entry point, hands the engine a per-session credential. It takes precedence over the other two. If the variable is not set, a warning is written on the typescript and the token from <code>FileStoreToken</code> or <code>FileStoreTokenFile</code>, if there is one, is used.
|-
| <code>FileStoreMaxMB «scheme» = «n»</code> || The largest file, in megabytes, that will be fetched from this store. Default 256. A fetch that exceeds it is aborted with an error that names this setting.
|-
| <code>FileStoreTimeoutS «scheme» = «n»</code> || The read timeout, in seconds. Default 60. The connect timeout is fixed at 5 seconds.
|}

The <code>FileStore</code> line must come first for a scheme. Any of the other keys naming a scheme that has not been declared yet is ignored, with a warning on the typescript (see [[#Diagnostics|Diagnostics]] for where that appears in each product).

The URL may include a path prefix, as in <code>http://host:port/prefix</code>. A trailing <code>/</code> is dropped, and the endpoints the engine calls are appended to what remains.

'''The URL must be <code>http://</code>.''' An <code>https://</code> URL is refused when the provider is registered, with a warning on the typescript, because TLS is not compiled into the engine's HTTP client. The deployments this supports are a store service on <code>localhost</code>, or one inside the same private network or cluster. See [[#Security|Security]] below.

The configuration is read '''once per process''', during engine initialization. Editing <code>FileProviders.config</code> has no effect until Analytica is restarted.

== Where Analytica looks for FileProviders.config ==

Four locations are consulted in this order, and the first one that names a file wins.

# '''The host's own command line option''', <code>/stores:«path»</code> -- see [[Analytica Command Line]].
# '''The environment variable <code>ANALYTICA_FILE_PROVIDERS_CONFIG</code>''', naming the file. This gives one process its own configuration without touching the registry -- for example a per-session file that a container's entry point writes before it starts the engine. It works for every product, ADE and ADEW included. If the variable names a file that does not exist, no providers are registered and a warning is written on the typescript.
# '''The <code>FileProvidersConfig</code> registry value.''' Two keys are consulted, and each is looked for under <code>HKEY_CURRENT_USER</code> first and then under <code>HKEY_LOCAL_MACHINE</code>:
#* <code>HKCU\Software\Lumina Decision Systems\«product»\«version»\FileProvidersConfig</code> -- per product and per version, for example <code>...\Analytica\7.2</code> or <code>...\ADEW\7.2</code>. Use this when you want one product to see a different set of stores from the others.
#* <code>HKCU\SOFTWARE\Lumina Decision Systems\FileProvidersConfig</code> -- product-independent. One value here serves Analytica, [[ADE]] and ADEW, [[ACP]] and [[AMP]] alike. This is the usual choice, and, apart from the environment variable, it is the only way to set the location for ADE and ADEW, which have no command line of their own.
#: A value that names a file which does not exist produces a warning on the typescript, rather than quietly registering nothing.
# '''<code>FileProviders.config</code> in the same folder as the engine binary''' -- the deployed default.

When none of these finds a file, no providers are registered and nothing is reported.

== Using a provider from a model ==

Once <code>repo</code> has been declared, use it as an ordinary file name.

:<code>[[ReadTextFile]]( "repo://data/Sales.csv" )</code>
:<code>[[ReadBinaryFile]]( "repo://data/logo.png" )</code>
:<code>[[FileExists]]( "repo://models/My Model.ana" )</code>

[[FileSystemListing]] returns the names, sizes and modification dates that the store reports:

:<code>[[FileSystemListing]]( "repo://models/", recurse: true )</code>
:<code>[[FileSystemListing]]( "repo://data/*.csv", ['Name', 'Size', 'DateLastModified'] )</code>

A wildcard in the last segment of the path filters the listing, as it does for a local folder.

You can open a model whose path is a URI. Modules that the model links to or includes resolve relative to the model's own URI, so a model at <code>repo://models/Main.ana</code> that includes <code>sub\Child.ana</code> loads <code>repo://models/sub/Child.ana</code> from the same store. [[FileFullPath]] joins a relative name onto a URI folder the same way:

:<code>[[FileFullPath]]( "Q3.csv", "repo://Sales" ) → 'repo://Sales/Q3.csv'</code>

An [[Obfuscated and Browse-Only Models|obfuscated model]] works over a provider scheme exactly as it does from a local file.

A long transfer stays cancellable. Ctrl+Break, or a cancellation from an [[ACP]] or [[AMP]] client, interrupts a fetch that is in progress instead of waiting for it to finish.

=== Existence checks ===

The [[FileExists]] function asks the store. An object stored at that exact key is a file. A folder is recognized from the store's listing of its parent folder, since a store normally exposes a folder only as a listing prefix and answers "not found" when asked about it directly. Name matching is case-sensitive, as it is in the store itself. When the store cannot be reached, or rejects the credentials, [[FileExists]] reports that error rather than guessing an answer -- the modeler asked a question, and a wrong answer would be worse than an error.

The existence tests the engine makes '''on its own''', while resolving a model and the modules it links to, use a plain HTTP <code>HEAD</code> request and take the opposite tack, deliberately: if the store cannot be reached, or rejects the credentials, the test reports '''exists''' -- it cannot prove absence. Control then reaches the code that actually opens the file, and ''that'' reports the real transport or authentication problem, instead of a misleading "file not found".

=== Writing and saving ===

[[WriteTextFile]], [[WriteBinaryFile]] and saving a model -- '''Save''', '''Save As''' and '''Save a copy''' -- work with a URI path. The file is written to a local temporary file and uploaded whole, in one request, when it is closed. Whether a location accepts writes is up to the store service: a store, or part of one, can be read-only, and a write to it then fails with ''the repo:// file store is read-only and refused the write (HTTP 405)''.

=== Creating, copying, moving and deleting ===

[[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]] and [[FileSystemDelete]] work on URI paths, and behave as they do on a local disk: a trailing <code>/</code> on the destination means "into this folder", «replace» and «deleteNonEmptyFolder» mean the same thing, deleting a file that is not there returns [[Null]] rather than an error, and the error messages are the same. The differences are:
* [[FileSystemNewFolder]] creates any missing parent folders.
* A store has no read-only attribute and no links, so the «deleteReadOnly» parameter of [[FileSystemDelete]] and the «copyLinks» parameter of [[FileSystemCopy]] are ignored.
* Within one store, a copy or move -- of a file or of a whole folder -- is carried out by the store service itself. Between two different stores, or between a store and the local disk, a '''single file''' can be copied or moved: the engine reads it from one and writes it to the other. Copying or moving a '''folder''' between stores is refused.
* If a move cannot delete its source -- because the source is in a read-only part of the store, for example -- the copy it has just made is removed again and the error is reported, so a failed move never leaves the file in two places.

:<code>[[FileSystemNewFolder]]( "Q3", "repo://Sales" )</code>
:<code>[[FileSystemCopy]]( "repo://Sales/Q3/draft.csv", "repo://Sales/Q3/final.csv" )</code>
:<code>[[FileSystemMove]]( "repo://Sales/Q3", "repo://Archive/" )</code>
:<code>[[FileSystemDelete]]( "repo://Archive/Q3", deleteNonEmptyFolder: true )</code>

=== Spreadsheets ===

[[SpreadsheetOpen]] accepts a URI path, and always uses the LibXL backend for one. The Excel backend opens files through Windows and cannot reach a store, so <code>backend: 'Excel'</code> is refused for a URI path. The workbook is read from the store in one fetch. [[SpreadsheetSave]] writes it back in one upload -- to the path it came from when no «filename» is given, or to any other path, local or URI.

:<code>Local wb := [[SpreadsheetOpen]]( "repo://Sales/Q3.xlsx" );</code>
:<code>[[SpreadsheetSetCell]]( wb, "Sheet1", "B", 2, 1250 );</code>
:<code>[[SpreadsheetSave]]( wb )</code>

A workbook sitting next to a model that was opened from a URI can be named relative to the model, as any other file can.

== Restrictions in Analytica 7.2 ==

* '''Whole-file writes.''' A write uploads the complete file when it is closed. There is no appending or partial update on the store side.
* '''Folders stay within one store.''' Only a single file can be copied or moved from one store to another, or between a store and the local disk.
* '''Atomicity is the service's.''' A folder copy or move inside one store is done by the store service, so whether it is atomic depends on the service. A git-backed store can make it one commit; a service over an object bucket typically copies object by object.
* '''Whole-file fetch.''' A read pulls the entire file, subject to <code>FileStoreMaxMB</code>. It is not a seekable remote stream, so a provider path is not a good way to peek at a few bytes of a very large file.
* '''One short fetch cache.''' The URI most recently fetched is cached for 10 seconds, because opening a model reads the same file two or three times. Past that, every read goes to the store.
* '''No file browser.''' A URI path never poses a "locate the file" dialog. A file that is not there is reported as not found.

== Diagnostics ==

Everything the provider layer reports itself is written to the '''typescript''' -- the engine's typescript output. Where to look for it depends on which product you are running: in Analytica it appears in the [[Typescript Window|typescript window]]; [[ADE]] and ADEW capture the typescript as their log, and so does [[ACP]]; and in [[AMP]] the typescript is echoed to <code>stderr</code>, which is the server log, so <code>Amp.exe</code> users find these lines on stderr. AMP is the only product where stderr is the right place to look.

On start-up, each registered provider prints one line:

<pre>
[FileProviders] repo:// -> http://mystore.internal:8080
</pre>

Unrecognized lines, unusable scheme names, an <code>https://</code> URL, a token file that could not be read, a <code>FileProvidersConfig</code> registry value or an <code>ANALYTICA_FILE_PROVIDERS_CONFIG</code> environment variable naming a file that is not there, and a <code>FileStoreTokenEnv</code> variable that is not set, each produce their own warning there. An '''absent''' configuration file is silent: no providers are registered and nothing is written.

Errors that reach the model name the file -- for example ''The file '...' could not be opened'' -- and give one of these explanations:

{| class="wikitable"
! Situation !! What it says
|-
| No provider is registered for that scheme || <code>no file provider is registered for the scheme 'repo'</code>
|-
| The edition does not include the feature || <code>'repo://' paths require the Developer edition or better</code>, also naming the edition you do have
|-
| The store rejected the credentials (HTTP 401 or 403) || <code>the repo:// file store rejected the credentials (HTTP 401)</code>
|-
| Any other unexpected HTTP status || <code>HTTP «n» from the repo:// file store</code>
|-
| The service could not be reached || <code>could not reach the repo:// file store (...)</code>
|-
| The file is larger than the cap || <code>the file exceeds the «n» MB fetch limit (FileStoreMaxMB in FileProviders.config)</code>
|-
| A <code>..</code> segment in the path || <code>'..' is not allowed in a repo:// path</code>
|-
| The store refused a write, because that location is read-only (HTTP 405) || <code>the repo:// file store is read-only and refused the write (HTTP 405)</code>
|-
| Creating a file that is already there, where it must not be overwritten || <code>'Sales/Q3.csv' already exists in the repo:// file store</code>
|-
| An upload larger than the store accepts (HTTP 413) || <code>the repo:// file store refused the upload as too large (HTTP 413)</code>
|-
| The store service does not implement the write or file-management endpoint that was needed || <code>the repo:// file store does not support this operation (the store service may need to be updated)</code>
|}

HTTP 404 is not an error. It means the file is not there, and the caller then reports a missing file in its usual way.

Copying or moving a folder between stores, and asking for the Excel backend on a URI path, are refused by [[FileSystemCopy]], [[FileSystemMove]] and [[SpreadsheetOpen]] with messages of their own that say why.

== Security ==

The connection between Analytica and a store service is '''plain HTTP''', with no TLS. That is a deliberate limitation of this release, and you have to design around it:

* The bearer token, and the file contents, travel '''in the clear''' over that hop. Run the store service on <code>localhost</code>, or on a private network or cluster network that you already trust with that traffic. Do not put a store service anywhere you would not be willing to send the token in plain text.
* <code>FileProviders.config</code> can hold a token, so protect it like any other file holding a secret. Restrict who can read it, and keep it out of version control and out of model archives.
* Prefer <code>FileStoreTokenFile</code> to <code>FileStoreToken</code>. It keeps the token out of the file that gets copied from machine to machine, and it lets the token live somewhere with tighter permissions -- or, in a container, be a mounted secret.
* Where a launcher starts the engine -- a container entry point, a session manager -- <code>FileStoreTokenEnv</code> is better still: the token never touches a disk, and the engine removes the variable from its own environment as soon as it has read it, so the model it runs cannot read the token back.
* A store service should authenticate every request, and should reject path traversal itself. The engine refuses a <code>..</code> segment before any request is sent, but a service must not rely on that.

== See Also ==
* '''[[Custom file system providers/API spec]]''' -- the HTTP API that a store service must implement
* [[Analytica Command Line]] -- the <code>/stores:«path»</code> option
* [[ReadTextFile]]
* [[ReadBinaryFile]]
* [[FileExists]]
* [[FileSystemListing]]
* [[FileFullPath]]
* [[FilePathPart]]
* [[WriteTextFile]]
* [[FileSystemNewFolder]], [[FileSystemCopy]], [[FileSystemMove]], [[FileSystemDelete]]
* [[SpreadsheetOpen]], [[SpreadsheetSave]]
* [[:Category:File system functions]]

RunConsoleProcess

2026-09-22T23:31:47Z

Lchrisman: RunConsoleProcess in linux note

[[Category:Integration Functions]]
{{ReleaseBar}}

== RunConsoleProcess(program, ''cmdLine, stdIn, block, curDir, priority, showErr{{Release|7.1||, path}}'') ==

[[RunConsoleProcess]] lets an Analytica model run a ''console process'' -- that is, any Windows program. The program may be very simple with no graphical user interface that takes input from «stdIn» and writing output to ''stdOut'' -- or it may interact with the user directly. [[RunConsoleProcess]] gives the path and name of the application in the «program» parameter. It can feed input to the program via command line parameters in «cmdLine», or as input data given as text to the «stdIn» parameter, which is piped to the ''StdIn'' input channel of the console process. Normally, when the process completes, [[RunConsoleProcess]] will return a result (as text) any information the program writes to ''stdOut''. Analytica can also send data to a console process via a data files created with [[WriteTextFile]] or receive a data file created by the process using [[ReadTextFile]].

==Declaration ==
<pre style="background:white; border:white; margin-left: 1em;">
RunConsoleProcess(
program: Atomic Text,
cmdLine: Optional Atomic Text,
stdIn: Optional Atomic Text,
block: Optional Atomic Boolean, /* default TRUE */
curDir: Optional Atomic Text, /* default process directory */
priority: Optional Atomic Number, /* default 0 = normal, same as Ana */
showErr: Optional Numeric) /* defaults to 1 = err msg */
</pre>
{{Release|7.1||
In [[Analytica 7.1]] and later, «program» and «cmdLine» are individually optional (you must supply at least one), and there is a new optional named «path» parameter:
<pre style="background:white; border:white; margin-left: 1em;">
RunConsoleProcess(
program: Optional Atomic Text,
cmdLine: Optional Atomic Text,
stdIn: Optional Atomic Text,
block: Optional Atomic Boolean, /* default TRUE */
curDir: Optional Atomic Text, /* default process directory */
priority: Optional Atomic Number, /* default 0 = normal, same as Ana */
showErr: Optional Numeric, /* defaults to 1 = err msg */
path: Optional Atomic Text) /* defaults to %PATH% */
</pre>
}}

[[RunConsoleProcess]] offers considerable flexibility through a number of other optional parameters:

«block»: By default (or if you set «block» to <code>True</code> or <code>1</code>), [[RunConsoleProcess]] ''blocks'' -- that is, Analytica waits until the console process terminates and returns a result before it resumes execution. While blocked, Analytica still notices Windows events: If you press ''Ctrl+break'' (or ''Ctrl+.'') before the process terminates, it kills the process, and ends further computation by Analytica -- just like what it does when Analytica is computing without another process.

If you pass <code>False</code> (<code>0</code>) to «block», [[RunConsoleProcess]] will not wait for the process to terminate: It immediately returns an empty text to Analytica. Analytica and the spawned process both continue running concurrently until they each terminate. If you press ''Ctrl+break'' (or ''Ctrl+.''), it interrupts any computations by Analytica, but has no effect on the spawned process. An unblocked process is independent, and may continue running even after you exit Analytica. Unblocked processes are useful when you want to send data to another application for display, such as a special graphing package or GIS, or for saving selected results. It is hard to get any results or status back to Analytica from an unblocked process. It is usually best to use a blocked process if you need results back.

The «program» and «cmdLine» parameters are separated, rather than lumped together as one parameter, to protect against a common type of virus attack.

«curDir»: Any relative directory path specified in the program parameter is interpreted relative to Analytica's [[CurrentDataFolder]]. «curDir» specifies the directory the spawned process should use as its default directory to read and write files. If «curDir» is not specified, it uses its own directory as its default .

«priority» defines the priority that Windows should give the spawned process relative to the Analytica process. The default (<code>0</code>) runs the new process at the same priority as the Analytica program. A value of <code>–1</code> or <code>-2</code> lowers the priority, allowing other programs more of the CPU. A value of <code>+1</code> or <code>+2</code> raises the priority, dedicating more of the CPU to the process.

«showErr»: By default, in blocking mode, if the process writes anything to ''stdErr'', Analytica will display it as an error message when the process terminates. If <code>showErr = 2</code> it shows any text in ''stdErr'' as a warning message. If <code>showErr = 0</code>, and always in non-blocking mode, it ignores anything in ''stdErr''. {{Release|7.2||When running a Linux command in a Linux operating system, you may need <code>showError:0</code> or <code>showError:2</code> more often since Linux tools write warnings to stderr more readily.}}

'''Errors''': Analytica will give an error message if [[RunConsoleProcess]] cannot find or launch the specified program.

[[RunConsoleProcess]] fully supports [[Intelligent Arrays]]: If any parameter is passed an array, it will run a separate process for each element of the array. It runs multiple blocking processes in sequence, one after another. It runs multiple non-blocking processes concurrently.

{{Release|7.1||
== Combined command line and CMD built-ins ==
''New to [[Analytica 7.1]]''

If you specify just one of «program» or «cmdLine» (and not both), it is treated as the entire command line, and Analytica locates the executable for you. So these two calls are equivalent:
:<code>RunConsoleProcess("ffmpeg.exe", "ffmpeg -i input.mp4 output.mp3")</code>
:<code>RunConsoleProcess("ffmpeg -i input.mp4 output.mp3")</code>

You must specify at least one of «program» or «cmdLine»; calling [[RunConsoleProcess]] with neither raises an error. The original two-parameter form is still supported and recommended when you want to be explicit about which is the executable.

In this combined-command-line form, if the first word names a built-in <code>CMD.EXE</code> command (such as <code>DIR</code>, <code>ECHO</code>, <code>COPY</code>, <code>TYPE</code>, <code>SET</code>, <code>MOVE</code>, <code>DEL</code>, …), Analytica automatically runs the command through CMD.EXE — that is, as <code>cmd /c «cmdLine»</code>. For example:
:<code>RunConsoleProcess("DIR *.txt")</code>
runs as <code>cmd /c DIR *.txt</code> and returns the directory listing.

Shell operators such as <code>&&</code>, <code>||</code>, <code>|</code>, <code>></code> and <code><</code> are interpreted by CMD.EXE, not by [[RunConsoleProcess]] itself. If your command line uses them — for example, to run several commands in a single shell session so their side effects persist — put it after <code>cmd /c</code> explicitly:
:<code>RunConsoleProcess("cmd /c conda activate Env1 && pip install desiredlib")</code>

«path»: An optional named parameter giving the <code>;</code>-separated search path used to locate the executable when you use the combined-command-line form. It defaults to the <code>%PATH%</code> environment variable. Use it to restrict (or extend) the search when running a tool that isn't in the system PATH:
:<code>RunConsoleProcess("ffmpeg -i input.mp4 output.mp3", path: "C:\Tools\ffmpeg\bin")</code>
:<code>RunConsoleProcess("MyTool", path: "C:\MyTools;%PATH%")</code>

If the executable is not found in «path», [[RunConsoleProcess]] raises a "could not launch" error rather than silently falling back to the system search path. «path» has no effect when both «program» and «cmdLine» are given, since in that mode «program» already names the executable explicitly.
}}

{{Release|6.5||
== Using Environment Variables ==
''New to [[Analytica 6.5]]''

You can substitute the value of environment variables into the «program», «cmdLine» or «curDir» parameters using <code>%name%</code>. For example:

:<code>[[RunConsoleProcess]]( "%windir%\system32\cscript.exe", "cscript /NoLogo HelloWorld.vbs", curDir:"%TEMP%" )</code>

If you need to actually pass a % character in one of those parameters, then double it, e.g., <code>"%%"</code>.
}}

== Examples ==
=== VB Script ===
Suppose the file <code>HelloWorld.vbs</code> is in your model directory and contains:

:<code>WScript.Echo "Hello World"</code>

Your call to [[RunConsoleProcess]] might look like:

:<code>RunConsoleProcess("{{Release||6.4|C:\Windows}}{{Release|6.5||%windir%}}\System32\CScript.exe",</code>
::<code>"CScript/Nologo HelloWorld.vbs")</code>

The first parameter is the program (usually an ''EXE'' file) to be launched. You don't need to worry about quoting any spaces in the path name. The second parameter is the command line as it might appear on a command prompt. This expression will evaluate to the string "Hello World".

If you need to send data to the ''StdIn'' of the process, include an optional parameter «stdIn»:
:<code>RunConsoleProcess("{{Release||6.4|C:\Windows}}{{Release|6.5||%windir%}}\System32\CScript.exe",</code>
::<code>"CScript/Nologo HelloWorld.vbs", </code>
::<code>StdIn: MyDataToSend)</code>

where <code>MyDataToSend</code> evaluates to a text.

=== Batch File ===
In this example, a batch file named <code>DoIt.bat</code> is in the directory <code>C:\Try</code>. Also in that directory is a file named <code>data.log</code>. The batch file, <code>DoIt.bat</code> contains the following:

:<code># DoIt.bat -- dump the log</code>
:<code>Type data.log</code>

This batch file assumes it is run from the directory <code>C:\Try</code>. {{Release||6.4|First, set up a Constant node:
:<code>Constant CMD := [[GetProcessInfo]]("env:comspec")</code>
which most commonly ends up with }}{{Release|6.5||This uses the <code>%comspec%</code> environment variable to find the CMD command, which most commonly has }}the value <code>"C:\Windows\System32\Cmd.exe"</code>. Then the call is:

:<code>RunConsoleProcess({{Release||6.4|CMD}}{{Release|6.5||"%comspec%", </code>
::<code>"Cmd /C DoIt.bat",</code>
::<code>CurDir: "C:\Try")</code>

or you can run it directly:

:<code>RunConsoleProcess("DoIt.bat", "DoIt.bat", CurDir: "C:\Try")</code>

=== Reading Data from a URL ===

If you want to read data from a URL, you should use the [[ReadFromURL]] function. Nevertheless, this example from the past may be illustrative.

To read the contents of a web page given its URL, you can use:
:<code>RunConsoleProcess("ReadURL.exe", "ReadURL " & url)</code>

where ''url'' is a text string as would appear in the address bar of your browser. You can download the [[media:ReadURL.exe | ReadURL.exe]] program by clicking on the link and saving. The first parameter to [[RunConsoleProcess]] may need to be set to the full path where you placed [[media:ReadURL.exe | ReadURL.exe]] unless you put it in your [[CurrentDataFolder]].

A step-by-step example using [[media:ReadURL.exe | ReadURL.exe]] is given here: [[Retrieving Content From the Web]]. This example includes the source code for [[media:ReadURL.exe | ReadURL.exe]], and develops an example that obtains historical stock price data from the Yahoo finance web site.

==History==
This function was introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].

Ability to use environment variables in «program», «cmdLine» and «curDir» was added in [[Analytica 6.5]].

{{Release|7.1||In [[Analytica 7.1]], «program» and «cmdLine» became individually optional. When only one is given, it is treated as a combined command line; if the first word is a CMD.EXE built-in such as <code>DIR</code> or <code>ECHO</code>, it is run via <code>cmd /c</code> automatically. A new optional named «path» parameter (default <code>%PATH%</code>) can scope where the executable is searched for.}}

== See Also ==
* Webinar: [https://webinars.analytica.com/Docs/2007-10-18-Calling-External-Applications.mp4 Calling-External-Applications.mp4]
* [[CurrentDataFolder]]
* [[WriteTextFile]]
* [[ReadTextFile]]
* [[GetRegistryValue]]

File:Example of Encrypt and Decrypt.ana

2026-09-22T20:15:10Z

Lchrisman: Lchrisman uploaded a new version of File:Example of Encrypt and Decrypt.ana

== Summary ==
Very simple illustration of the strong encryption functions.

File:Example of Encrypt and Decrypt.ana

2026-09-22T20:10:44Z

Lchrisman: Very simple illustration of the strong encryption functions.

== Summary ==
Very simple illustration of the strong encryption functions.

Encrypting and decrypting

2026-09-22T20:10:13Z

Lchrisman: /* See Also */ added example model

[[category:Encrypting and hashing functions]]

{{ReleaseBar}}

''New to [[Analytica 7.2]].''

''Requires [[Analytica Developer]] edition or better.''

Analytica can encrypt and decrypt data using strong, standard, ''authenticated'' encryption. The four functions live in the '''<code>Crypto</code>''' namespace:

* [[#EncryptionKey|Crypto::EncryptionKey]] -- makes a key, which is a value of its own data type.
* [[#Encrypt|Crypto::Encrypt]] -- seals text or binary data under a key.
* [[#Decrypt|Crypto::Decrypt]] -- opens a sealed value, or reports an error if anything about it has changed.
* [[#RandomBytes|Crypto::RandomBytes]] -- cryptographically random bytes, for salts and keys.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] MyKey := Crypto::EncryptionKey( password: 'correct horse battery staple', salt: Salt )</code>
: <code>[[Variable]] Sealed := Crypto::Encrypt( 'launch codes', MyKey )</code>
: <code>[[Variable]] Plain := Crypto::Decrypt( Sealed, MyKey ) → 'launch codes'</code>

== The Crypto namespace ==

These are specialist functions, so they are not in your model's namespace to begin with. A model that never encrypts anything is not troubled by them, and they cannot collide with your own identifiers. You reach them in either of two ways.

'''Qualify each call''' with <code>Crypto::</code>, as in the example above. Nothing is needed to make this work.

'''Or import the namespace once.''' Put <code>Crypto</code> on a line of its own in your model's [[NamespaceImports]] attribute, and then write the names bare:

: <code>Encrypt( 'launch codes', MyKey )</code>

The rest of this page writes <code>Crypto::</code> explicitly so that each example works whether or not you have imported the namespace.

== What authenticated encryption means ==

All four algorithms here are ''AEAD'' ciphers -- Authenticated Encryption with Associated Data. Along with the encrypted data, a sealed value carries an ''authentication tag'' computed from the key. [[#Decrypt|Crypto::Decrypt]] checks the tag before it returns anything, so a sealed value that has been altered -- even by a single bit, even by someone who cannot read it -- produces an error instead of altered data.

This is what you want, and it is not what simpler schemes give you. Encryption on its own hides data but does not stop an attacker from changing it in ways that change the decrypted result predictably. Nothing on this page lets you do unauthenticated encryption, deliberately.

The error from a failed decryption is deliberately the same whether the key was wrong, the «aad» was wrong, or the data was altered. Telling those cases apart would help an attacker work out a key one guess at a time.

== Keys ==

A key is a value of its own type, made by [[#EncryptionKey|Crypto::EncryptionKey]]. It carries the algorithm along with the key material, so a key and an algorithm can never disagree, and [[#Encrypt|Crypto::Encrypt]] needs no «algorithm» parameter.

'''Make the key its own variable.''' Deriving a key from a password takes a noticeable fraction of a second by design (see [[#Passwords and salts|Passwords and salts]]). When the key is a variable, Analytica computes it once and reuses it, so encrypting a whole column of a table costs one derivation, not one per cell. Writing the derivation inline inside [[#Encrypt|Crypto::Encrypt]] would repeat it for every cell.

The key material itself cannot be read from any expression. Printing a key shows only what it is:

: <code>MyKey → «EncryptionKey AES-256-GCM #7a2f»</code>

A key has four readable members:

* <code>MyKey->algorithm</code> -- <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>.
* <code>MyKey->keyBits</code> -- 128, 192 or 256.
* <code>MyKey->fingerprint</code> -- four hexadecimal digits that identify the key without revealing it. Two keys are the same key if and only if their fingerprints match (to a very high probability). Useful for answering "did this deployment get the key I think it did?" without ever displaying a key.
* <code>MyKey->fromSecret</code> -- [[True]] when the key material came from a [[Secret]].

=== Passwords and salts ===

<code>Crypto::EncryptionKey( password: p, salt: s )</code> stretches a password into a key using PBKDF2-HMAC-SHA-256 with «iterations» rounds, 600,000 by default. The iterations are the point: they make each guess at your password expensive for an attacker, which is the only defence a human-chosen password has.

The «salt» is '''not''' secret. Keep it in an ordinary variable next to the key, and save it with your model -- you need the same salt to derive the same key again. Its job is to make precomputed attack tables useless, which it does even though it is public. Make one with <code>[[#RandomBytes|Crypto::RandomBytes]](16)</code> and then leave it alone; changing the salt changes the key, and data encrypted under the old key can no longer be read.

=== Keeping the key out of the model ===

If the key is written in the model, anyone who has the model has the key, and the encryption protects nothing. The usual arrangement is the other way round: the ''sealed data'' travels in the <code>.ana</code> file and the ''key'' does not.

Give «key» or «password» a [[Secret]] to do that. The secret's value reaches the key derivation without ever entering the model as a value:

: <code>Crypto::EncryptionKey( key: MyKeySecret )</code>
: <code>Crypto::EncryptionKey( password: MyPasswordSecret, salt: Salt )</code>

The [[Secret]] needs two things set before Analytica will allow this:

* '''Sinks''' must list <code>EncryptionKey</code>.
* '''Destination''' must be the single word <code>local</code>. Unlike a URL or a database connection string, key material never leaves the Analytica process, so there is no destination to pin -- but the setting is still required, so that allowing it is a deliberate act.

Consider also setting the secret's '''Caller''' to the module that is allowed to build the key, which restricts the use of the secret far more tightly than any destination could.

A key made from a [[Secret]] refuses <code>->Export()</code>, and reads <code>fromSecret = True</code>. That is deliberate: a secret's value must never come back into the model, and exporting the key it produced would be exactly that.

=== Generating and saving a key ===

<code>Crypto::EncryptionKey()</code> with no arguments makes a fresh random key. To use the same key again later, export the material and store it somewhere outside the model -- a [[Secret]], a file, a password manager:

: <code>Crypto::EncryptionKey()->Export() → a 32-byte binary value</code>

To see it as text you can copy, format it:

: <code>f"{Crypto::EncryptionKey()->Export():b}" → base64'8Xk2wQ...'</code>

Paste that <code>base64'...'</code> literal back into an expression to rebuild the same key:

: <code>Crypto::EncryptionKey( key: base64'8Xk2wQ...' )</code>

'''A key cannot be stored in a variable''' the way other values can. Assigning one to a variable's definition is refused, because that would write the key material into the <code>.ana</code> file. Build the key where it is used instead.

== Sealed values ==

[[#Encrypt|Crypto::Encrypt]] returns [[In-memory binary data terms|binary data]] by default. The <code>'analytica'</code> container adds 36 bytes to whatever you encrypted: a marker that says this is an Analytica sealed value, which algorithm made it, whether the plaintext was text or binary, the nonce, and the authentication tag.

Because the container records whether the plaintext was text or binary, [[#Decrypt|Crypto::Decrypt]] hands back the same kind of value you encrypted, with nothing extra to say.

=== Every call produces a different result ===

Each call draws a fresh random ''nonce'', so encrypting the same text twice gives two different sealed values. That is required -- reusing a nonce with the same key breaks the encryption completely -- but it has a practical consequence in a model: a sealed value computed by a definition changes every time the definition is re-evaluated.

So do not leave <code>Crypto::Encrypt(...)</code> in the definition of a variable whose result you intend to keep. Compute the sealed value once, in a button script, and assign it:

: <code>Sealed := Crypto::Encrypt( Plaintext, MyKey )</code>

The assignment writes the sealed value into <code>Sealed</code>'s definition as a <code>base64'...'</code> literal, which is saved with the model and decrypts unchanged when it is reopened.

=== Binding a sealed value to its context ===

The optional «aad» parameter -- additional authenticated data -- is authenticated but not encrypted. Whoever decrypts must supply the same «aad» or the decryption fails.

Use it to tie each sealed value to where it belongs. If you seal a column of salaries with no «aad», someone who cannot read them can still swap two rows and go undetected. Seal them with the employee as «aad» and the swap is caught:

: <code>Crypto::Encrypt( Salary, MyKey, aad: Employee )</code>
: <code>Crypto::Decrypt( SealedSalary, MyKey, aad: Employee )</code>

The «aad» is not secret and does not need to be hidden -- the reader has to know it anyway.

== Encrypting a whole table ==

«data» and «aad» are atomic parameters, so both functions [[Array Abstraction|array abstract]]. One expression seals an entire indexed table, each cell under its own fresh nonce, all under the one key:

: <code>[[Variable]] SealedRows := Crypto::Encrypt( PlainRows, MyKey )</code>
: <code>[[Variable]] PlainAgain := Crypto::Decrypt( SealedRows, MyKey )</code>

This is where making the key its own variable pays off: the key is derived once and every cell reuses it.

== Interoperating with other systems ==

To exchange sealed data with something outside Analytica, you need to agree on two things: how the bytes are packaged, and how they are written as text.

=== Layouts ===

There is no single universal convention for packaging a nonce, a ciphertext and an authentication tag, so «layout» lets you pick the one your counterpart uses.

{| class="wikitable"
! «layout» !! The sealed value contains !! Used by
|-
| <code>'analytica'</code> (default) || A self-describing container: marker, algorithm, text-or-binary flag, nonce, tag, ciphertext || Analytica
|-
| <code>'nonce,ct,tag'</code> || nonce, then ciphertext, then tag || The common Go idiom, and most published examples
|-
| <code>'ct,tag'</code> || ciphertext, then tag; the nonce is separate || Python's <code>cryptography</code> package, libsodium
|-
| <code>'nonce,tag,ct'</code> || nonce, then tag, then ciphertext ||
|-
| <code>'none'</code> || the bare ciphertext; nonce and tag are separate || Node.js <code>crypto</code>, .NET <code>AesGcm</code>
|}

Whatever the layout, the nonce and the tag are '''also''' available as the second and third return values, so you can always get at them:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

and supply them again when decrypting a layout that does not carry them:

: <code>Crypto::Decrypt( ct, MyKey, nonce: n, tag: t, layout: 'none', as: 'text' )</code>

The raw layouts carry no record of whether the plaintext was text or binary, so «as» is required with them.

=== Text encodings ===

«format» writes the sealed value as text instead of binary data -- <code>'base64'</code>, <code>'base64url'</code> (the URL-safe alphabet, no padding) or <code>'hex'</code>. [[#Decrypt|Crypto::Decrypt]] reads text in the same encodings.

: <code>Crypto::Encrypt( 'hello', MyKey, format: 'base64' )</code>
: <code>Crypto::Decrypt( sealedText, MyKey, format: 'base64' )</code>

=== A worked example ===

This Python produces a value Analytica reads, and reads a value Analytica produced. It uses the <code>cryptography</code> package.

<pre>
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64

key = bytes(range(32)) # the same 32 bytes as base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8='
nonce = bytes(range(12))

# Seal something for Analytica
ct = AESGCM(key).encrypt(nonce, 'from python'.encode('utf-8'), b'ctx7')
print(base64.b64encode(nonce + ct).decode())

# Open something Analytica sealed with layout:'ct,tag'
plain = AESGCM(key).decrypt(nonce, bytes.fromhex('66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'), None)
print(plain.decode('utf-8')) # -> hello
</pre>

In Analytica:

: <code>[[Variable]] K := Crypto::EncryptionKey( key: base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=' )</code>
: <code>Crypto::Decrypt( base64'AAECAwQFBgcICQoLIXC5duWVu2/lLvmrU3Xrc1+3jRqJx0hC/3QKjDlK2w==', K, layout: 'nonce,ct,tag', aad: 'ctx7', as: 'text' ) → 'from python'</code>
: <code>Crypto::Encrypt( 'hello', K, nonce: base64'AAAAAAAAAAAAAAAA', layout: 'ct,tag', format: 'hex' ) → '66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'</code>

The «nonce» parameter is used here only to make the output reproducible so it can be checked against a published test vector. '''Do not supply a nonce in real use.''' Reusing a nonce with the same key destroys the security of the encryption completely; omitting it is always the right thing.

=== The 'analytica' container ===

If you need to read Analytica's own container from another language, its bytes are:

{| class="wikitable"
! Offset !! Length !! Field
|-
| 0 || 4 || The four characters <code>ACRY</code>
|-
| 4 || 1 || Format version, currently 1
|-
| 5 || 1 || Algorithm: 1 = AES-128-GCM, 2 = AES-192-GCM, 3 = AES-256-GCM, 4 = ChaCha20-Poly1305
|-
| 6 || 1 || Flags. Bit 0 set means the plaintext was text, encoded as UTF-8. Bit 1 set means an «aad» was supplied.
|-
| 7 || 1 || Nonce length, 12 for every algorithm above
|-
| 8 || 12 || Nonce
|-
| 20 || 16 || Authentication tag
|-
| 36 || rest || Ciphertext
|}

The salt and the iteration count are '''not''' in the container. They belong to the key, which you construct explicitly, so keep the salt in a variable of your own next to the key that uses it.

= Function reference =

<span id="EncryptionKey"></span>
== Crypto::EncryptionKey( ''algorithm, key, keyFormat, password, salt, iterations, kdf'' ) ==
''Requires [[Analytica Developer]] edition or better.''

Creates a key for [[#Encrypt|Crypto::Encrypt]] and [[#Decrypt|Crypto::Decrypt]]. Give it either «key» or «password», or neither for a fresh random key.

=== Parameters ===

* «algorithm»: (optional, default <code>'AES-256-GCM'</code>) One of <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>. ChaCha20-Poly1305 requires Windows 10 version 1903 or later; on an older system it reports that it is unavailable rather than failing obscurely.

* «key»: (optional) Raw key material, as [[In-memory binary data terms|binary data]] -- usually a <code>base64'...'</code> literal. It must be exactly the algorithm's key length: 32 bytes for AES-256-GCM and ChaCha20-Poly1305, 24 for AES-192-GCM, 16 for AES-128-GCM. A key of the wrong length is an error; Analytica will not pad or hash it to fit, because that would quietly weaken it. You may also pass a [[Secret]] here, in which case the secret's text is decoded according to «keyFormat». Plain text that is not a [[Secret]] is refused -- use «password» for a passphrase.

* «keyFormat»: (optional, default <code>'base64'</code>) How to read the text a [[Secret]] holds: <code>'base64'</code>, <code>'base64url'</code>, <code>'hex'</code> or <code>'utf8'</code>. Meaningful only when «key» is given a [[Secret]].

* «password»: (optional) A passphrase to derive the key from. Requires «salt». May be given a [[Secret]].

* «salt»: (optional) Text or [[In-memory binary data terms|binary data]], at least 8 bytes, required whenever «password» is given. Not secret; see [[#Passwords and salts|Passwords and salts]].

* «iterations»: (optional, default 600000) PBKDF2 rounds. More is slower and safer. Use the same number every time, or you get a different key.

* «kdf»: (optional, default <code>'PBKDF2-HMAC-SHA-256'</code>) The key-derivation function. This release supports only that one; the parameter exists so that adding others later does not change how you write the call.

A parameter that could not take effect is refused rather than quietly ignored -- «iterations» without «password», for example.

=== Members ===

<code>->algorithm</code>, <code>->keyBits</code>, <code>->fingerprint</code> and <code>->fromSecret</code>, described under [[#Keys|Keys]]. There is no member that returns the key material.

<span id="Export"></span>
== key->Export( ) ==

Returns the raw key material of a key as [[In-memory binary data terms|binary data]]. This is the only way to get key material back out, and it is meant for saving a randomly generated key so the same key can be used again.

: <code>MyKey->Export() → a 32-byte binary value</code>

A key derived from a [[Secret]] cannot be exported, and reports an error. A secret's value is never allowed back into the model.

<span id="Encrypt"></span>
== Crypto::Encrypt( data, key'', aad, nonce, format, layout'' ) ==
''Requires [[Analytica Developer]] edition or better.''

Encrypts «data» under «key» and returns a sealed value that only the same key can open. Returns [[Null]] when «data» is [[Null]].

=== Parameters ===

* «data»: Text or [[In-memory binary data terms|binary data]]. A number is refused rather than converted, since <code>42</code> could reasonably mean either the text <code>'42'</code> or eight bytes -- use <code>[[Text]](x)</code> if you mean its textual form.

* «key»: A key from [[#EncryptionKey|Crypto::EncryptionKey]]. The algorithm comes from the key.

* «aad»: (optional) Additional authenticated data -- authenticated but not encrypted. [[#Decrypt|Crypto::Decrypt]] must be given the same value. See [[#Binding a sealed value to its context|Binding a sealed value to its context]].

* «nonce»: (optional, named) Supplies the nonce instead of generating one. '''Reusing a nonce with the same key destroys the security of the encryption completely.''' Omit this unless you are reproducing a published test vector or another system's exact output.

* «format»: (optional, named, default <code>'binary'</code>) <code>'binary'</code>, <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>.

* «layout»: (optional, named, default <code>'analytica'</code>) See [[#Layouts|Layouts]].

=== Return value ===

The sealed value, as [[In-memory binary data terms|binary data]] or as text according to «format». The nonce and the authentication tag are returned as the second and third return values:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

It [[Array Abstraction|array abstracts]] over «data» and «aad», sealing each cell under its own nonce.

<span id="Decrypt"></span>
== Crypto::Decrypt( data, key'', aad, nonce, tag, format, layout, as'' ) ==
''Requires [[Analytica Developer]] edition or better.''

Opens a value sealed by [[#Encrypt|Crypto::Encrypt]]. Returns [[Null]] when «data» is [[Null]].

Reports an error if the value cannot be decrypted -- wrong key, wrong «aad», or data that has been altered. The message deliberately does not say which, because that distinction would help an attacker. Use [[Try]] if your model should carry on regardless.

=== Parameters ===

* «data»: The sealed value, as [[In-memory binary data terms|binary data]], or as text in the encoding named by «format».

* «key»: The same key the value was sealed with. If it is a key for a different algorithm, that is reported specifically, since it is a mistake you can act on rather than a failed decryption.

* «aad»: (optional) Must equal the «aad» the value was sealed with.

* «nonce», «tag»: (optional, named) Required for a «layout» that does not carry them.

* «format»: (optional, named, default <code>'base64'</code>) How to read a textual «data»: <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>. Ignored when «data» is binary.

* «layout»: (optional, named, default <code>'analytica'</code>) Must match the layout the value was sealed with. See [[#Layouts|Layouts]].

* «as»: (optional, named) <code>'text'</code> or <code>'binaryData'</code>. With the default <code>'analytica'</code> layout it is optional, because the sealed value records which one was encrypted. For every other layout it is required. <code>'text'</code> reports an error if the decrypted bytes are not valid UTF-8, which is usually a sign that you wanted <code>'binaryData'</code>.

<span id="RandomBytes"></span>
== Crypto::RandomBytes( n ) ==

Returns «n» cryptographically random bytes as [[In-memory binary data terms|binary data]]. Use it for a «salt», or for raw key material.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] NewKey := Crypto::EncryptionKey( key: Crypto::RandomBytes(32) )</code>

«n» may not exceed 65536.

Each evaluation returns different bytes. Like [[#Encrypt|Crypto::Encrypt]], this means a definition that calls it does not hold still across re-evaluations -- assign the result once if you need it to stay the same.

== Errors ==

Most mistakes are reported specifically, and can be caught with [[Try]]:

* The «key» is the wrong length for the algorithm, or «key» was given plain text rather than key material or a [[Secret]].
* Both «key» and «password» were given, or «password» was given without a «salt», or a parameter such as «iterations» cannot take effect.
* The algorithm is not one of the four, or is not available on this computer.
* «data» is a number rather than text or binary data.
* The sealed value is not an Analytica sealed value, or was sealed with a different algorithm, or the text is not valid for the stated «format».
* A [[Secret]] was passed where a secret makes no sense, such as «aad» or «salt», neither of which is secret.
* <code>->Export()</code> was called on a key derived from a [[Secret]].

The one deliberately vague error is a failed decryption, described under [[#Decrypt|Crypto::Decrypt]].

== See Also ==

* [[Secret]] -- keeping a key out of the model
* [[TextCharacterEncode]] -- hashing text with SHA-1 or SHA-256, and other text encodings
* [[In-memory binary data terms]]
* [[NamespaceImports]]
* [[:category:Encrypting and hashing functions|Encrypting and hashing functions]]
* [[media:Example of Encrypt and Decrypt.ana|Example of Encrypt and Decrypt.ana]]

What's new in Analytica 7.2?

2026-09-22T18:23:19Z

Lchrisman: ER 22440 - Encrypt, Decrypt

Analytica 7.2 is currently under development, and will be a future release of Analytica. The current official release is [[Analytica 7.1]]. This page is under construction, and will list enhancements that are new to Analytica or ADE 7.2.

== Secrets ==
The [[Secret]] object class is a first-class home for the credentials your model uses: database passwords, API keys, bearer tokens.

A Secret keeps the credential itself out of the language entirely. The Secret's identifier evaluates to a ''placeholder'' text, e.g. <code><nowiki>{{secret:AcmeKey}}</nowiki></code>, which you compose into a connection string or URL like any other text:

:<code>DbQuery(f"DSN=AcmeWarehouse;UID=svc_reports;PWD={AcmeKey}", sql)</code>

The real value is substituted only inside allow-listed built-in functions ([[DbQuery]], [[ReadFromUrl|ReadFromURL]], [[OAuth2Authorize]], and the other database functions), in compiled code, just before the text goes to ODBC or to the web -- and only when the call's destination matches the Secret's declared policy. Definitions stay fully readable, with no cloaking or locked modules -- yet the credential never appears in any result, attribute, error message, or saved file, and model code cannot exfiltrate it (a <code>WriteTextFile</code> or a <code>ReadFromURL</code> aimed at some other server never sees the real value).

Create one with '''[[Object menu]] / New / Secret''' (requires the Developer edition; models ''containing'' secrets load and run in every edition). See [[Secret]] for the full story, including an honest account of what each storage kind does and does not protect against.

== Custom File Providers ==
(''advanced, esoteric'')
A [[Custom file system providers|file system provider]] makes a URI-style path, <code>«scheme»://«root»/«path»</code>, for example <code>"repo://Sales/Q3.csv"</code>, work anywhere the Analytica engine accepts a file name. The file provider can be a source other than a file system (for example, a git repo, cloud storage, a web-based document management system, etc.), but from Analytica and within your models, it can be used anywhere a file path would be used, as if it were a file. You have to configure the available file providers, and you can implement your own (e.g., to wrap an existing service) according to a document [[Custom file system providers/API spec|API specification]].

== GUI ==
* The [[Object menu]] has a new submenu named '''New''', which you can use to add a new object of any class. This makes it easier and more convenient to add more esoteric class instances that aren't on the toolbar (like Frame node, Struct, Callable, Secret, etc.) Plus it is easier to add a new node without using a mouse.
** '''[[Object menu]] / New / Picture''' prompts for an image filename. (similar to '''[File menu] / Import...'''.
* Enhancements to the [[Outline window]]
** There are now hover icons on line items.
** You can Alt+Click on an item in the Outline to insert its identifier while editing an expression elsewhere.
** The '''Module only''' checkbox has been removed from the header, and a new icon button added to each module line item to show or hide non-module children, allowing this to be controlled at the level of each module or library.
** Key strokes now have an effect. Up/Down arrows move between line items. Right/Left arrows from a module expand or collapse that item. Shift+Right/Left from a module show or hide non-module children. Home/End keys jump to the begging or end. And typing characters incrementally search among the items visible in the window.
* Input and Output popups are now present on Module nodes in a diagram. Input popups appear when you click to the immediately left of a node, and output popups appear when you click to the immediate right of a node. These have long existed for variables enabling you to quickly navigate dependencies, but for a Module node the situation is much more complex. A dependency exists from Module A to Module B when there exists a dependency between variables <code>X→Y</code> where X is within Module A and Y is within Module B. With modules, there can be a very large number of such dependencies, so the new module input/output popups are organized hierarchically with expanding outline views.
* There is a new [[Publish To Cloud dialog]]. It handles both ACP3 (the current version at https://acp.analytica.com at the time of this release) as well as ACP4 (coming soon).
* A user input node with a '''[List]''' control pops up a new list-editor dialog, similar to the one in ACP. Previously this opened the Object Window where you would edit the list. The new dialog focuses solely on the list without all the other attributes.
* Added Drag-and-drop of selected text within and between textual attribute values. Formerly required Cut-Paste, but differs in that Drag-and-drop doesn't alter the clipboard.
* The [[Preferences dialog]] exposes some new preference settings:
** The method used when generating identifiers from titles. (Which Assista will also use when naming objects)
** Whether display-only arrows should be show as dashed.
** The time zone used for new date-time values (such as when parsing dates).

== Built-in functions or structs ==
* The [[Functions To Read Excel Worksheets|Spreadsheet functions]] now work directly with live Google sheets.
* A new option to <code>[[SpreadsheetInfo]]( wb, 'Backend')</code>, to programatically detect which backend the workbook uses (<code>'LibXl'</code>, <code>'Excel'</code> or <code>'GoogleSheets'</code>).
* [[FileExists]]( filepath'', files, folders'' ) tests whether a file or folder exists, without the [[FileSystemListing]] idiom that this used to require. Requires {{Analytica Developer}} or better.
* New parameters, «map» and «includeNull» added to [[Flatten]] (...). Makes it easy and efficient to concatenate a collection of lists when the lists are behind [[references]] or in [[Struct]] members.
* [[SortIndex]], [[Sort]] and [[Rank]] can now accept a «lessThat» function for custom comparisons. See [[Using an ordering function when sorting]].
* A new optional «timeZone» parameter added to [[ParseDate]], [[ParseCSV]], [[NumberToText]], and [[Today]]. Controls which time zone a newly created date-time number (such as when parsed) is created in. [[ParseDate]] and [[ParseCSV]] now recognize ISO 8601 and RFC 3339 date-time format; These are used by many web services, and may include an explicit time zone, which gets converted into the active or specified time zone.
* Added new built-in functions for [[Encrypting and decrypting|encryption and decryption]] using strong, standard authenticated encryption. (requires [[Analytica Developer]] edition or better).
* (Esoteric) A new parameter, «sensitive», to [[AskMsgText]] and [[MsgBox]]. Used with the new <code>/AutomationTrace</code> [[Analytica Command Line|command line]] option to prevent sensitive info (like a credential or API key) from being logged.
* (''Experimental'') New [[Timer]] struct for scheduling an evaluation.
* New options for [[GetProcessInfo]] to detect non-Windows host version (e.g., when running on Linux), as well as installed fonts.
* (Esoteric) A new Struct, [[ArrowDependencies]], returns detailed information on dependencies into, or out of, nodes. Most useful for finding all the dependencies between two modules (i.e., which variables deep inside are responsible for dependencies between them). Introduce to enable Assista to better answer questions about module dependencies.
* The [[UncertainLMH]] distribution now allows «xLow»=«lb» or «xHigh»=«ub». This means that 10% (or more generally «pLow») of the probability sits at the «lb» or «ub» value creating a discontinuity in the CDF (an infinite spike in the PDF) at that value.
* Added an «asIndex» parameter to [[HandleFromIdentifier]]. The same already existed on [[Handle]]. Used to disambiguate in the case of a self-indexed array-valued variable.
* When <code>[[Area]](y,x)</code> or <code>[[Integrate]](y,x)</code> appear in a [[DefineOptimization]] formulation where <code>y</code> depends on decision variables, the analyzer recognizes this as a linear or quadratic relationship when deciding whether the problem is an «LP», «QP» or «NLP».

== Dates and time zones ==
* ISO 8601 / RFC 3339 date-times with a UTC offset, such as <code>2025-08-25T00:07:05.000+0000</code> (the form most web APIs return), are now parsed by [[ParseDate]], [[ParseCSV]], table cells and definitions, and can be written as literals inside expressions, e.g., <code>Sequence(2025-08-25T00:00:00, 2025-08-27T00:00:00, dateUnit: 'D')</code>. See [[Date and Time Values]].
* A new model preference, '''Time zone''' ([[Preferences dialog]]; system variable [[System variables#Sys_TimeZone|Sys_TimeZone]], default <code>'Local'</code>), says which time zone the model's date-time values are in. Text with an explicit offset is converted into it, and [[Today]]() reports the time in it.
* A new «timeZone» parameter on [[ParseDate]], [[ParseCSV]], [[Today]] and [[NumberToText]]: <code>'Model'</code>, <code>'Local'</code>, <code>'UTC'</code> or a fixed offset such as <code>'+05:30'</code>.
* A new date format, <code>'ISO8601'</code> (equivalent to <code>yyyy-MM-ddTHH:mm:ss.sssZ</code>), and date template codes <code>Z</code>, <code>ZZ</code> and <code>ZZZ</code> for the UTC offset, so timestamps can be sent back to an API: <code>NumberToText(x, dateFormat: 'ISO8601', timeZone: 'UTC')</code>. See [[Date formats]].
* '''Behavior change''': a trailing <code>Z</code> on a parsed date-time, e.g. <code>ParseDate('2025-08-25T00:07:05Z')</code>, was accepted but ignored in 7.0 and 7.1. It now means UTC, so such values shift by your zone's offset from UTC. A literal <code>Z</code> in a custom date template must now be quoted (<code>'Z'</code>).

== New command line options ==
See [[Analytica Command Line]].
*; <code>/evalThenExit:«expression»</code>: Like <code>/eval:</code>, but Analytica exits as soon as «expression» has finished, without asking whether to save changes. It replaces the <code>/eval:"«expression»;EvaluateScript('Bye -')"</code> idiom that a [[Running a model in a command line workflow|command line workflow]] used to need, and that was easy to forget.

*; <code>/lib:«YourLib.ana»</code>: Loads an Analytica library into [[SysLib_Customizations]], which exists concurrently with your model (in a different [[Namespace]]). It survives across model closures, so it can appear as new built-in functionality. Useful for [[MCP server in Analytica|MCP Servers]], QA testing, benchmarking, [[Running a model in a command line workflow|batch processing]], GUI extensions, General (model-independent) [[Assista - Analytica AI Assistant/Custom user skills for Assista|Custom Assista skill libraries]], etc.

*; <code>/Automation</code> and <code>/AutomationTrace:«file»</code>: Run in an automation mode so that blocking modal dialogs don't appear waiting for a user input.

*; <code>/WindowXY</code> and <code>/WindowSize</code>: Explicit control over the initial location of the Analytica application window on your screen.

*; <code>/stores:«path to FileProvider.config»</code>: Location of a [[Custom file system providers|Custom file system provider]] configuration file.

*; <code>/remote-debugging-port:«port»</code> and <code>/remote-allow-origins:«origins»</code>: Hooks used by Lumina for Assista benchmarking and AI-assisted debugging during GUI development.

*; <code>/Autosave=0</code> or <code>/Autosave=1</code>: Turns the ''Maintain recovery info'' preference off or on for that run only, without changing the stored preference (and <code>/Automation</code> now implies <code>/Autosave=0</code>).

== AI Integration ==
* You can now use an [[MCP server in Analytica|MCP server implemented in desktop Analytica]] from Claude.ai, Claude CoWork and other AI clients that are running in the Cloud (when used in conjunction with a tunnel such as <code>cloudflared</code> or <code>ngrok</code>).

== Evaluation engine ==
* [[Null]] can be specified to a repeated index parameter, which is a way to specify the implicit dimension (aka the null index). All such repeated index parameters for all built-in functions handle this. This enables <code>...[[IndexesOf]](x)</code> to work when <code>x</code> has an implicit dimension without any extra surrounding code.
* Introduced a new function parameter qualifier, <code>nullIndexOk</code>, for a non-repeated index parameter. When this is specified, the caller can specify [[Null]] for the index with the meaning that the function should operate over the implicit dimension.

== Misc ==
* The limit on the maximum number of objects (which was 65500) has been removed. There is no longer any fixed limit.
* Dynamic calculations now use new attributes, <code>dynValue</code> and <code>dynProbValue</code> for partial results, and the usual <code>Value</code> and <code>probValue</code> only for fully computed results. Previously partial results during a dynamic calculation were tracked in <code>Value</code> and <code>probValue</code>.
* The identifier <code>Date</code> is no longer a reserved identifier, and hence can be used as an identifier in your own models. The previous attribute, which encodes "Created date" for models, modules, and libraries, is still present as <code>SysLib_Internal::Date</code>. Model file format is unchanged by this.

Encrypting and decrypting

2026-09-22T18:08:45Z

Lchrisman: Added "Requires Developer edition"

Encrypting and decrypting

2026-09-22T17:58:17Z

Lchrisman: /* Function reference */ italicized optional params

[[category:Encrypting and hashing functions]]

{{ReleaseBar}}

''New to [[Analytica 7.2]].''

Analytica can encrypt and decrypt data using strong, standard, ''authenticated'' encryption. The four functions live in the '''<code>Crypto</code>''' namespace:

* [[#EncryptionKey|Crypto::EncryptionKey]] -- makes a key, which is a value of its own data type.
* [[#Encrypt|Crypto::Encrypt]] -- seals text or binary data under a key.
* [[#Decrypt|Crypto::Decrypt]] -- opens a sealed value, or reports an error if anything about it has changed.
* [[#RandomBytes|Crypto::RandomBytes]] -- cryptographically random bytes, for salts and keys.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] MyKey := Crypto::EncryptionKey( password: 'correct horse battery staple', salt: Salt )</code>
: <code>[[Variable]] Sealed := Crypto::Encrypt( 'launch codes', MyKey )</code>
: <code>[[Variable]] Plain := Crypto::Decrypt( Sealed, MyKey ) → 'launch codes'</code>

== The Crypto namespace ==

These are specialist functions, so they are not in your model's namespace to begin with. A model that never encrypts anything is not troubled by them, and they cannot collide with your own identifiers. You reach them in either of two ways.

'''Qualify each call''' with <code>Crypto::</code>, as in the example above. Nothing is needed to make this work.

'''Or import the namespace once.''' Put <code>Crypto</code> on a line of its own in your model's [[NamespaceImports]] attribute, and then write the names bare:

: <code>Encrypt( 'launch codes', MyKey )</code>

The rest of this page writes <code>Crypto::</code> explicitly so that each example works whether or not you have imported the namespace.

== What authenticated encryption means ==

All four algorithms here are ''AEAD'' ciphers -- Authenticated Encryption with Associated Data. Along with the encrypted data, a sealed value carries an ''authentication tag'' computed from the key. [[#Decrypt|Crypto::Decrypt]] checks the tag before it returns anything, so a sealed value that has been altered -- even by a single bit, even by someone who cannot read it -- produces an error instead of altered data.

This is what you want, and it is not what simpler schemes give you. Encryption on its own hides data but does not stop an attacker from changing it in ways that change the decrypted result predictably. Nothing on this page lets you do unauthenticated encryption, deliberately.

The error from a failed decryption is deliberately the same whether the key was wrong, the «aad» was wrong, or the data was altered. Telling those cases apart would help an attacker work out a key one guess at a time.

== Keys ==

A key is a value of its own type, made by [[#EncryptionKey|Crypto::EncryptionKey]]. It carries the algorithm along with the key material, so a key and an algorithm can never disagree, and [[#Encrypt|Crypto::Encrypt]] needs no «algorithm» parameter.

'''Make the key its own variable.''' Deriving a key from a password takes a noticeable fraction of a second by design (see [[#Passwords and salts|Passwords and salts]]). When the key is a variable, Analytica computes it once and reuses it, so encrypting a whole column of a table costs one derivation, not one per cell. Writing the derivation inline inside [[#Encrypt|Crypto::Encrypt]] would repeat it for every cell.

The key material itself cannot be read from any expression. Printing a key shows only what it is:

: <code>MyKey → «EncryptionKey AES-256-GCM #7a2f»</code>

A key has four readable members:

* <code>MyKey->algorithm</code> -- <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>.
* <code>MyKey->keyBits</code> -- 128, 192 or 256.
* <code>MyKey->fingerprint</code> -- four hexadecimal digits that identify the key without revealing it. Two keys are the same key if and only if their fingerprints match (to a very high probability). Useful for answering "did this deployment get the key I think it did?" without ever displaying a key.
* <code>MyKey->fromSecret</code> -- [[True]] when the key material came from a [[Secret]].

=== Passwords and salts ===

<code>Crypto::EncryptionKey( password: p, salt: s )</code> stretches a password into a key using PBKDF2-HMAC-SHA-256 with «iterations» rounds, 600,000 by default. The iterations are the point: they make each guess at your password expensive for an attacker, which is the only defence a human-chosen password has.

The «salt» is '''not''' secret. Keep it in an ordinary variable next to the key, and save it with your model -- you need the same salt to derive the same key again. Its job is to make precomputed attack tables useless, which it does even though it is public. Make one with <code>[[#RandomBytes|Crypto::RandomBytes]](16)</code> and then leave it alone; changing the salt changes the key, and data encrypted under the old key can no longer be read.

=== Keeping the key out of the model ===

If the key is written in the model, anyone who has the model has the key, and the encryption protects nothing. The usual arrangement is the other way round: the ''sealed data'' travels in the <code>.ana</code> file and the ''key'' does not.

Give «key» or «password» a [[Secret]] to do that. The secret's value reaches the key derivation without ever entering the model as a value:

: <code>Crypto::EncryptionKey( key: MyKeySecret )</code>
: <code>Crypto::EncryptionKey( password: MyPasswordSecret, salt: Salt )</code>

The [[Secret]] needs two things set before Analytica will allow this:

* '''Sinks''' must list <code>EncryptionKey</code>.
* '''Destination''' must be the single word <code>local</code>. Unlike a URL or a database connection string, key material never leaves the Analytica process, so there is no destination to pin -- but the setting is still required, so that allowing it is a deliberate act.

Consider also setting the secret's '''Caller''' to the module that is allowed to build the key, which restricts the use of the secret far more tightly than any destination could.

A key made from a [[Secret]] refuses <code>->Export()</code>, and reads <code>fromSecret = True</code>. That is deliberate: a secret's value must never come back into the model, and exporting the key it produced would be exactly that.

=== Generating and saving a key ===

<code>Crypto::EncryptionKey()</code> with no arguments makes a fresh random key. To use the same key again later, export the material and store it somewhere outside the model -- a [[Secret]], a file, a password manager:

: <code>Crypto::EncryptionKey()->Export() → a 32-byte binary value</code>

To see it as text you can copy, format it:

: <code>f"{Crypto::EncryptionKey()->Export():b}" → base64'8Xk2wQ...'</code>

Paste that <code>base64'...'</code> literal back into an expression to rebuild the same key:

: <code>Crypto::EncryptionKey( key: base64'8Xk2wQ...' )</code>

'''A key cannot be stored in a variable''' the way other values can. Assigning one to a variable's definition is refused, because that would write the key material into the <code>.ana</code> file. Build the key where it is used instead.

== Sealed values ==

[[#Encrypt|Crypto::Encrypt]] returns [[In-memory binary data terms|binary data]] by default. The <code>'analytica'</code> container adds 36 bytes to whatever you encrypted: a marker that says this is an Analytica sealed value, which algorithm made it, whether the plaintext was text or binary, the nonce, and the authentication tag.

Because the container records whether the plaintext was text or binary, [[#Decrypt|Crypto::Decrypt]] hands back the same kind of value you encrypted, with nothing extra to say.

=== Every call produces a different result ===

Each call draws a fresh random ''nonce'', so encrypting the same text twice gives two different sealed values. That is required -- reusing a nonce with the same key breaks the encryption completely -- but it has a practical consequence in a model: a sealed value computed by a definition changes every time the definition is re-evaluated.

So do not leave <code>Crypto::Encrypt(...)</code> in the definition of a variable whose result you intend to keep. Compute the sealed value once, in a button script, and assign it:

: <code>Sealed := Crypto::Encrypt( Plaintext, MyKey )</code>

The assignment writes the sealed value into <code>Sealed</code>'s definition as a <code>base64'...'</code> literal, which is saved with the model and decrypts unchanged when it is reopened.

=== Binding a sealed value to its context ===

The optional «aad» parameter -- additional authenticated data -- is authenticated but not encrypted. Whoever decrypts must supply the same «aad» or the decryption fails.

Use it to tie each sealed value to where it belongs. If you seal a column of salaries with no «aad», someone who cannot read them can still swap two rows and go undetected. Seal them with the employee as «aad» and the swap is caught:

: <code>Crypto::Encrypt( Salary, MyKey, aad: Employee )</code>
: <code>Crypto::Decrypt( SealedSalary, MyKey, aad: Employee )</code>

The «aad» is not secret and does not need to be hidden -- the reader has to know it anyway.

== Encrypting a whole table ==

«data» and «aad» are atomic parameters, so both functions [[Array Abstraction|array abstract]]. One expression seals an entire indexed table, each cell under its own fresh nonce, all under the one key:

: <code>[[Variable]] SealedRows := Crypto::Encrypt( PlainRows, MyKey )</code>
: <code>[[Variable]] PlainAgain := Crypto::Decrypt( SealedRows, MyKey )</code>

This is where making the key its own variable pays off: the key is derived once and every cell reuses it.

== Interoperating with other systems ==

To exchange sealed data with something outside Analytica, you need to agree on two things: how the bytes are packaged, and how they are written as text.

=== Layouts ===

There is no single universal convention for packaging a nonce, a ciphertext and an authentication tag, so «layout» lets you pick the one your counterpart uses.

{| class="wikitable"
! «layout» !! The sealed value contains !! Used by
|-
| <code>'analytica'</code> (default) || A self-describing container: marker, algorithm, text-or-binary flag, nonce, tag, ciphertext || Analytica
|-
| <code>'nonce,ct,tag'</code> || nonce, then ciphertext, then tag || The common Go idiom, and most published examples
|-
| <code>'ct,tag'</code> || ciphertext, then tag; the nonce is separate || Python's <code>cryptography</code> package, libsodium
|-
| <code>'nonce,tag,ct'</code> || nonce, then tag, then ciphertext ||
|-
| <code>'none'</code> || the bare ciphertext; nonce and tag are separate || Node.js <code>crypto</code>, .NET <code>AesGcm</code>
|}

Whatever the layout, the nonce and the tag are '''also''' available as the second and third return values, so you can always get at them:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

and supply them again when decrypting a layout that does not carry them:

: <code>Crypto::Decrypt( ct, MyKey, nonce: n, tag: t, layout: 'none', as: 'text' )</code>

The raw layouts carry no record of whether the plaintext was text or binary, so «as» is required with them.

=== Text encodings ===

«format» writes the sealed value as text instead of binary data -- <code>'base64'</code>, <code>'base64url'</code> (the URL-safe alphabet, no padding) or <code>'hex'</code>. [[#Decrypt|Crypto::Decrypt]] reads text in the same encodings.

: <code>Crypto::Encrypt( 'hello', MyKey, format: 'base64' )</code>
: <code>Crypto::Decrypt( sealedText, MyKey, format: 'base64' )</code>

=== A worked example ===

This Python produces a value Analytica reads, and reads a value Analytica produced. It uses the <code>cryptography</code> package.

<pre>
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64

key = bytes(range(32)) # the same 32 bytes as base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8='
nonce = bytes(range(12))

# Seal something for Analytica
ct = AESGCM(key).encrypt(nonce, 'from python'.encode('utf-8'), b'ctx7')
print(base64.b64encode(nonce + ct).decode())

# Open something Analytica sealed with layout:'ct,tag'
plain = AESGCM(key).decrypt(nonce, bytes.fromhex('66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'), None)
print(plain.decode('utf-8')) # -> hello
</pre>

In Analytica:

: <code>[[Variable]] K := Crypto::EncryptionKey( key: base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=' )</code>
: <code>Crypto::Decrypt( base64'AAECAwQFBgcICQoLIXC5duWVu2/lLvmrU3Xrc1+3jRqJx0hC/3QKjDlK2w==', K, layout: 'nonce,ct,tag', aad: 'ctx7', as: 'text' ) → 'from python'</code>
: <code>Crypto::Encrypt( 'hello', K, nonce: base64'AAAAAAAAAAAAAAAA', layout: 'ct,tag', format: 'hex' ) → '66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'</code>

The «nonce» parameter is used here only to make the output reproducible so it can be checked against a published test vector. '''Do not supply a nonce in real use.''' Reusing a nonce with the same key destroys the security of the encryption completely; omitting it is always the right thing.

=== The 'analytica' container ===

If you need to read Analytica's own container from another language, its bytes are:

{| class="wikitable"
! Offset !! Length !! Field
|-
| 0 || 4 || The four characters <code>ACRY</code>
|-
| 4 || 1 || Format version, currently 1
|-
| 5 || 1 || Algorithm: 1 = AES-128-GCM, 2 = AES-192-GCM, 3 = AES-256-GCM, 4 = ChaCha20-Poly1305
|-
| 6 || 1 || Flags. Bit 0 set means the plaintext was text, encoded as UTF-8. Bit 1 set means an «aad» was supplied.
|-
| 7 || 1 || Nonce length, 12 for every algorithm above
|-
| 8 || 12 || Nonce
|-
| 20 || 16 || Authentication tag
|-
| 36 || rest || Ciphertext
|}

The salt and the iteration count are '''not''' in the container. They belong to the key, which you construct explicitly, so keep the salt in a variable of your own next to the key that uses it.

= Function reference =

<span id="EncryptionKey"></span>
== Crypto::EncryptionKey( ''algorithm, key, keyFormat, password, salt, iterations, kdf'' ) ==

Creates a key for [[#Encrypt|Crypto::Encrypt]] and [[#Decrypt|Crypto::Decrypt]]. Give it either «key» or «password», or neither for a fresh random key.

=== Parameters ===

* «algorithm»: (optional, default <code>'AES-256-GCM'</code>) One of <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>. ChaCha20-Poly1305 requires Windows 10 version 1903 or later; on an older system it reports that it is unavailable rather than failing obscurely.

* «key»: (optional) Raw key material, as [[In-memory binary data terms|binary data]] -- usually a <code>base64'...'</code> literal. It must be exactly the algorithm's key length: 32 bytes for AES-256-GCM and ChaCha20-Poly1305, 24 for AES-192-GCM, 16 for AES-128-GCM. A key of the wrong length is an error; Analytica will not pad or hash it to fit, because that would quietly weaken it. You may also pass a [[Secret]] here, in which case the secret's text is decoded according to «keyFormat». Plain text that is not a [[Secret]] is refused -- use «password» for a passphrase.

* «keyFormat»: (optional, default <code>'base64'</code>) How to read the text a [[Secret]] holds: <code>'base64'</code>, <code>'base64url'</code>, <code>'hex'</code> or <code>'utf8'</code>. Meaningful only when «key» is given a [[Secret]].

* «password»: (optional) A passphrase to derive the key from. Requires «salt». May be given a [[Secret]].

* «salt»: (optional) Text or [[In-memory binary data terms|binary data]], at least 8 bytes, required whenever «password» is given. Not secret; see [[#Passwords and salts|Passwords and salts]].

* «iterations»: (optional, default 600000) PBKDF2 rounds. More is slower and safer. Use the same number every time, or you get a different key.

* «kdf»: (optional, default <code>'PBKDF2-HMAC-SHA-256'</code>) The key-derivation function. This release supports only that one; the parameter exists so that adding others later does not change how you write the call.

A parameter that could not take effect is refused rather than quietly ignored -- «iterations» without «password», for example.

=== Members ===

<code>->algorithm</code>, <code>->keyBits</code>, <code>->fingerprint</code> and <code>->fromSecret</code>, described under [[#Keys|Keys]]. There is no member that returns the key material.

<span id="Export"></span>
== key->Export( ) ==

Returns the raw key material of a key as [[In-memory binary data terms|binary data]]. This is the only way to get key material back out, and it is meant for saving a randomly generated key so the same key can be used again.

: <code>MyKey->Export() → a 32-byte binary value</code>

A key derived from a [[Secret]] cannot be exported, and reports an error. A secret's value is never allowed back into the model.

<span id="Encrypt"></span>
== Crypto::Encrypt( data, key'', aad, nonce, format, layout'' ) ==

Encrypts «data» under «key» and returns a sealed value that only the same key can open. Returns [[Null]] when «data» is [[Null]].

=== Parameters ===

* «data»: Text or [[In-memory binary data terms|binary data]]. A number is refused rather than converted, since <code>42</code> could reasonably mean either the text <code>'42'</code> or eight bytes -- use <code>[[Text]](x)</code> if you mean its textual form.

* «key»: A key from [[#EncryptionKey|Crypto::EncryptionKey]]. The algorithm comes from the key.

* «aad»: (optional) Additional authenticated data -- authenticated but not encrypted. [[#Decrypt|Crypto::Decrypt]] must be given the same value. See [[#Binding a sealed value to its context|Binding a sealed value to its context]].

* «nonce»: (optional, named) Supplies the nonce instead of generating one. '''Reusing a nonce with the same key destroys the security of the encryption completely.''' Omit this unless you are reproducing a published test vector or another system's exact output.

* «format»: (optional, named, default <code>'binary'</code>) <code>'binary'</code>, <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>.

* «layout»: (optional, named, default <code>'analytica'</code>) See [[#Layouts|Layouts]].

=== Return value ===

The sealed value, as [[In-memory binary data terms|binary data]] or as text according to «format». The nonce and the authentication tag are returned as the second and third return values:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

It [[Array Abstraction|array abstracts]] over «data» and «aad», sealing each cell under its own nonce.

<span id="Decrypt"></span>
== Crypto::Decrypt( data, key'', aad, nonce, tag, format, layout, as'' ) ==

Opens a value sealed by [[#Encrypt|Crypto::Encrypt]]. Returns [[Null]] when «data» is [[Null]].

Reports an error if the value cannot be decrypted -- wrong key, wrong «aad», or data that has been altered. The message deliberately does not say which, because that distinction would help an attacker. Use [[Try]] if your model should carry on regardless.

=== Parameters ===

* «data»: The sealed value, as [[In-memory binary data terms|binary data]], or as text in the encoding named by «format».

* «key»: The same key the value was sealed with. If it is a key for a different algorithm, that is reported specifically, since it is a mistake you can act on rather than a failed decryption.

* «aad»: (optional) Must equal the «aad» the value was sealed with.

* «nonce», «tag»: (optional, named) Required for a «layout» that does not carry them.

* «format»: (optional, named, default <code>'base64'</code>) How to read a textual «data»: <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>. Ignored when «data» is binary.

* «layout»: (optional, named, default <code>'analytica'</code>) Must match the layout the value was sealed with. See [[#Layouts|Layouts]].

* «as»: (optional, named) <code>'text'</code> or <code>'binaryData'</code>. With the default <code>'analytica'</code> layout it is optional, because the sealed value records which one was encrypted. For every other layout it is required. <code>'text'</code> reports an error if the decrypted bytes are not valid UTF-8, which is usually a sign that you wanted <code>'binaryData'</code>.

<span id="RandomBytes"></span>
== Crypto::RandomBytes( n ) ==

Returns «n» cryptographically random bytes as [[In-memory binary data terms|binary data]]. Use it for a «salt», or for raw key material.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] NewKey := Crypto::EncryptionKey( key: Crypto::RandomBytes(32) )</code>

«n» may not exceed 65536.

Each evaluation returns different bytes. Like [[#Encrypt|Crypto::Encrypt]], this means a definition that calls it does not hold still across re-evaluations -- assign the result once if you need it to stay the same.

== Errors ==

Most mistakes are reported specifically, and can be caught with [[Try]]:

* The «key» is the wrong length for the algorithm, or «key» was given plain text rather than key material or a [[Secret]].
* Both «key» and «password» were given, or «password» was given without a «salt», or a parameter such as «iterations» cannot take effect.
* The algorithm is not one of the four, or is not available on this computer.
* «data» is a number rather than text or binary data.
* The sealed value is not an Analytica sealed value, or was sealed with a different algorithm, or the text is not valid for the stated «format».
* A [[Secret]] was passed where a secret makes no sense, such as «aad» or «salt», neither of which is secret.
* <code>->Export()</code> was called on a key derived from a [[Secret]].

The one deliberately vague error is a failed decryption, described under [[#Decrypt|Crypto::Decrypt]].

== See Also ==

* [[Secret]] -- keeping a key out of the model
* [[TextCharacterEncode]] -- hashing text with SHA-1 or SHA-256, and other text encodings
* [[In-memory binary data terms]]
* [[NamespaceImports]]
* [[:category:Encrypting and hashing functions|Encrypting and hashing functions]]

Alphabetical Function List

2026-09-22T17:42:18Z

Lchrisman: ER 22440: add Decrypt, Encrypt, EncryptionKey, RandomBytes

[[Category:Functions]]
(Back to [[Analytica Reference]])

See also [[:Category: Functions]] and [[Functions by category]].

* [[Comparison Operators|=,<,>,<>,<=,>=]] : Comparison operators
* [[Subscript/Slice Operator| [I=x] ]] : Subscript operator
* [[Subscript/Slice Operator| [@I=x] ]] : Slice operator
* [[Using References|\]] : Reference operator
* [[Dereference Operator|#]] : Dereference operator
* [[Index Position Operator::@|@]] : Index Position operator
* [[Assignment Operator:: ::=|:=]] : Assignment operator
* [[Text Concatenation Operator: &|&]] : Text concatenation operator
* [[Dot operator::A.I|A.I]] : Dot operator, to access a local index of an array
* [[Repeated Parameter Forwarding|...]] : Repeated parameter forwarding
* [[Exponentiation of negative numbers|x^y]] : Exponentiation
* [[AbortCalculation]]
* [[Abs]]
* [[AddIndex]]
* [[Aggregate]]
* [[Airy_Ai]]
* [[Airy_Ai_deriv]]
* [[Airy_Ai_zero]]
* [[Airy_Bi]]
* [[Airy_Bi_deriv]]
* [[Airy_Bi_zero]]
* [[AnalyticaLicenseInfo]]
* [[And]]
* [[Apply_slicers_to_val]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[ArcCos]]
* [[ArcCosH]]
* [[ArcSin]]
* [[ArcSinH]]
* [[ArcTan]]
* [[ArcTan2]]
* [[ArcTanH]]
* [[Area]]
* [[ArgMin_and_ArgMax| Argmax]]
* [[ArgMin_and_ArgMax| Argmin]]
* [[Array]]
* [[Asc]]
* [[AskMsgChoice]]
* [[AskMsgNumber]]
* [[AskMsgText]]
* [[Assignment Operator:: ::=]] : Assignment operator
* [[AttribGet]]
* [[Attrib of Obj]]
* [[_AttTrackerQuery]]
* [[_AttTrackerReset]]
* [[Average]]
* [[Bernoulli]]
* [[BesselJ]], [[BesselY]], [[BesselI]], [[BesselK]]
* [[BesselJzero]], [[BesselYzero]]
* [[Beta]]
* [[Beta_m_sd|Beta_m_sd]] (Distribution variations.ana)
* [[Betafn]]
* [[BetaI]]
* [[BetaIaInv]]
* [[BetaIInv]]
* [[Binomial]]
* [[BiNormal]] (Multivariate distributions.ana)
* [[BitAnd]]
* [[BitCount]]
* [[BitNot]]
* [[BitOr]]
* [[BitShift]]
* [[BitXOr]]
* [[Boolean]]
* [[CAbs]] (Complex Library.ana)
* [[CAdjoint]] (Complex Library.ana)
* [[Calloption]] (Financial Library.ana)
* [[Canvas]]
* [[CanvasContext]]
* [[CanvasDrawEllipse]]
* [[CanvasDrawImage]]
* [[CanvasDrawLine]]
* [[CanvasDrawPixel]]
* [[CanvasDrawPolygon]]
* [[CanvasDrawRectangle]]
* [[CanvasDrawText]]
* [[CanvasImage]]
* [[Capm]] (Financial Library.ana)
* [[CArcCos]] (Complex Library.ana)
* [[CArcSin]] (Complex Library.ana)
* [[CArcTan]] (Complex Library.ana)
* [[CCos]] (Complex Library.ana)
* [[CDeterminant]] (Complex Library.ana)
* [[Cdf]]
* [[CDiv]] (Complex Library.ana)
* [[Ceil]]
* [[CellAlignment]]
* [[CellBar]]
* [[CellBorder]]
* [[CellDefaults]]
* [[CellEntry]]
* [[CellFill]]
* [[CellFont]]
* [[CellFormats]]
* [[CellIcon]]
* [[CellNumberFormat]]
* [[CellOnClick]]
* [[CellSpan]]
* [[Certain]]
* [[CExp]] (Complex Library.ana)
* [[ChanceDist]]
* [[ChangeArraySparsity]]
* [[Change_index]] (Expand Index.ana)
* [[ChangeNodeVisibility]]
* [[ChiSquared]]
* [[Choice| Choice]]
* [[CInverse]] (Complex Library.ana)
* [[Chr]]
* [[Clip_to_PlotArea]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[CLn]] (Complex Library.ana)
* [[CloneObjects]]
* [[CloseWindow]]
* [[CMatMult]] (Complex Library.ana)
* [[CMult]] (Complex Library.ana)
* [[Coerce_to_Numeric]] (Flat file library.ana)
* [[COMArray]]
* [[Combinations]]
* [[COMCallMethod]]
* [[COMCreateObject]]
* [[COMEnumerate]]
* [[COMGetProperty]]
* [[Comparison Operators]]: =, <, >, <>, <=, >=
* [[ComparisonPart]]
* [[Complex]] (Complex Library.ana)
* [[ComplexDegrees]]
* [[ComplexRadians]]
* [[CompressMemoryUsedBy]]
* [[ComputedBy]]
* [[COMPutProperty]]
* [[Concat]]
* [[ConcatN|Concat<N>]] (Concatenation UDFs.ana
* [[ConcatRows]] (Concatenation UDFs.ana)
* [[ConsolePrint]]
* [[Functions_Min_and_Max| Condmax]]
* [[Functions_Min_and_Max| Condmin]]
* [[ConsolePrint]]
* [[Continuous]]
* [[CopyIndex]]
* [[CopyToClipboard]]
* [[Correlate_Dists]] (Multivariate Distributions.ana)
* [[Correlate_With]] (Multivariate Distributions.ana)
* [[Correlation]]
* [[Trig Functions| Cos]]
* [[Trig Functions| Cosh]]
* [[CostCapme]] (Financial Library.ana)
* [[CostCapmm]] (Financial library.ana)
* [[CreateNewObject]]
* [[CRoots]] (Complex Library.ana)
* [[CSin]] (Complex Library.ana)
* [[CSqrt]] (Complex Library.ana)
* [[CTan]] (Complex Library.ana)
* [[CTheta]] (Complex Library.ana)
* [[CToPolar]] (Complex Library.ana)
* [[CubicInterp]]
* [[CumBinomial]] ([[Distribution Densities Library]])
* [[CumBinomialInv]] ([[Distribution Densities Library]])
* [[CumChiSquared]] ([[Distribution Densities Library]])
* [[CumChiSquaredInv]] ([[Distribution Densities Library]])
* [[CumDist]]
* [[CumExponential]] ([[Distribution Densities Library]])
* [[CumExponentialInv]] ([[Distribution Densities Library]])
* [[CumFDist]] ([[Distribution Densities Library]])
* [[CumFDistInv]] ([[Distribution Densities Library]])
* [[CumGeometric]] ([[Distribution Densities Library]])
* [[CumGeometricInv]] ([[Distribution Densities Library]])
* [[CumIPmt]]
* [[CumKeelin]]
* [[CumKeelinInv]]
* [[CumLogistic]] ([[Distribution Densities Library]])
* [[CumLogisticInv]] ([[Distribution Densities Library]])
* [[CumLogNormal]] ([[Distribution Densities Library]])
* [[CumLogNormalInv]] ([[Distribution Densities Library]])
* [[CumMax]]
* [[CumMin]]
* [[CumNegativeBinomial]] ([[Distribution Densities Library]])
* [[CumNegativeBinomInv]] ([[Distribution Densities Library]])
* [[CumNormal]]
* [[CumNormalInv]]
* [[CumPoisson]] ([[Distribution Densities Library]])
* [[CumPoissonInv]]
* [[CumPrinc]]
* [[CumProduct]]
* [[CumStudentT]] ([[Distribution Densities Library]])
* [[CumStudentTInv]] ([[Distribution Densities Library]])
* [[CumTriangular]] ([[Distribution Densities Library]])
* [[CumTriangularInv]] ([[Distribution Densities Library]])
* [[CumUncertainLMH]]
* [[CumUncertainLMHInv]]
* [[CumWilcoxon]]
* [[CumWilcoxonInv]]
* [[Cumulate]]
* [[CumUniform]] ([[Distribution Densities Library]])
* [[CumUniformInv]] ([[Distribution Densities Library]])
* [[CumWeibull]] ([[Distribution Densities Library]])
* [[CumWeibullInv]] ([[Distribution Densities Library]])
* [[CurrentDataDirectory]] (''Replaced with [[CurrentDataFolder]] as of [[Analytica 4.6]]'')
* [[CurrentDataFolder]]
* [[CurrentModelDirector]] (''Replaced with [[CurrentDataFolder]] as of [[Analytica 4.6]]'')
* [[CurrentModelFolder]]
* [[Expected value of information -- EVI, EVPI, and ESVI#Function CVI_x(v, d, xVars, pc)|CVI_x]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[DateAdd]]
* [[DatePart]]
* [[Dawson]]
* [[DbLabels]]
* [[DbQuery]]
* [[DbTable]]
* [[DbTablenames]]
* [[DbWrite]]
* [[Decompose]]
* [[Decrypt]]
* [[DeferWindowsResynch]]
* [[Degrees]]
* [[DensBeta]]
* [[Dens_Beta]] ([[Distribution Densities Library]])
* [[DensChiSquared]]
* [[Dens_ChiSquared]] ([[Distribution Densities Library]])
* [[DensCumDist]]
* [[Dens_CumDist]] ([[Distribution Densities Library]])
* [[DensExponential]]
* [[Dens_Exponential]] ([[Distribution Densities Library]])
* [[Dens_FDist]] ([[Distribution Densities Library]])
* [[DensGamma]
* [[Dens_Gamma]] ([[Distribution Densities Library]])
* [[DensGaussian]]
* [[Dens_Gaussian]] ([[Distribution Densities Library]])
* [[DensKeelin]]
* [[DensLogistic]]
* [[Dens_Logistic]] ([[Distribution Densities Library]])
* [[DensLogNormal]]
* [[Dens_LogNormal]] ([[Distribution Densities Library]])
* [[DensNormal]]
* [[Dens_Normal]] ([[Distribution Densities Library]])
* [[DensProbDist]]
* [[Dens_ProbDist]] ([[Distribution Densities Library]])
* [[DensStudentT]]
* [[Dens_StudentT]] ([[Distribution Densities Library]])
* [[DensTriangular]]
* [[Dens_Triangular]] ([[Distribution Densities Library]])
* [[DensUncertainLMH]]
* [[DensUniform]]
* [[Dens_Uniform]] ([[Distribution Densities Library]])
* [[DensWeibull]]
* [[Dens_Weibull]] ([[Distribution Densities Library]])
* [[Dereference Operator::#|Dereference Operator: #R]] : Return the value pointed to by a reference R.
* [[Determinant]]
* [[DetermTable]]
* [[Dirichlet]] (Multivariate distributions.ana)
* [[Discrete]]
* [[Dispatch]]
* [[Dist_additive_growth]] (Multivariate distributions.ana)
* [[Dist_compound_growth]] (Multivariate distributions.ana)
* [[Dist_reshape]] (Multivariate distributions.ana)
* [[Dist_serial_correl]] (Multivariate distributions.ana)
* [[DomainAllowed]]
* [[DomainIntegerGroup]]
* [[DomainLowerBound]]
* [[DomainNullOk]]
* [[DomainType]]
* [[DomainUpperBound]]
* [[DotProduct]]
* [[DownloadFileToClient]]
* [[Dydx]]
* [[Dynamic]]
* [[EigenDecomp]]
* [[Elasticity]]
* [[Encrypt]]
* [[EncryptionKey]]
* [[Erf]]
* [[ErfInv]]
* [[Erlang]] (Distribution variations.ana)
* [[Error]]
* [[Evaluate]]
* [[EvaluateScript]]
* [[Expected value of information -- EVI, EVPI, and ESVI#Function EVI_x(v, d, xVars)|EVI_x]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[Expected value of information -- EVI, EVPI, and ESVI#Function EVIU(v, d)|EVIU]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[Expected value of information -- EVI, EVPI, and ESVI#Function EVIU_by_x(v, d, xvars)|EVIU_by_x]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[Expected value of information -- EVI, EVPI, and ESVI#Function EVPI(v, d)|EVPI]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[Exp]]
* [[_Expm1]]
* [[Exponential]]
* [[expr1 ; expr2]] : Expression Sequence Operator
* [[Factorial]]
* [[Faddeeva]]
* [[FFT]]
* [[FFTInv]]
* [[FileFullPath]]
* [[FilePathPart]]
* [[FileSystemCopy]]
* [[FileSystemDelete]]
* [[FileSystemListing]]
* [[FileSystemMove]]
* [[FileSystemNewFolder]]
* [[FindInText]]
* [[FindObjects]]
* [[FindPolynomialZeroes]]
* [[Flatten]]
* [[Floor]]
* [[For..Do]]
* [[Fractiles]]
* [[Frequency]]
* [[FunctionOf]]
* [[Fv]]
* [[Gamma]]
* [[Gamma_m_sd|Gamma_m_sd]] (Distribution Variations.ana)
* [[GammaFn]]
* [[GammaI]]
* [[GammaIInv]]
* [[Gauss_Quadrature_Pts]] ([[Legendre Library]])
* [[Gaussian]]
* [[GCD]] ([[media:GCD function library.ana|GCD function library.ana]])
* [[Geometric]]
* [[GetArrowsOnDiagram]]
* [[GetEvaluationContext]]
* [[GetFract]]
* [[GetProcessInfo]]
* [[GetRegistryValue]]
* [[VarTerm Functions#Function_GetVariableByName| GetVariableByName]]
* [[GoalSeek]] (Optimization Functions.ana)
* [[Gradient]] (Optimization Functions.ana)
* [[GroupedInteger]]
* [[The Sensitivity Analysis Library#Importance Details|GRSensDetails]] ([[The Sensitivity Analysis Library]])
* [[HasImplicitDimension]]
* [[HasIndex]]
* [[HyperGeometric]]
* [[IdentPred]]
* [[If-Then-Else]]
* [[Ifall-Then-Else]]
* [[Ifonly-Then-Else]]
* [[If0]]
* [[Ifpos]]
* [[IgnoreWarnings]]
* [[Im]] (Complex Library.ana)
* [[ImageFromHex]]
* [[ImageInfo]]
* [[ImPart]]
* [[Implied_volatility_c]] (Financial library.ana)
* [[Implied_volatility_p]] (Financial library.ana)
* [[The Sensitivity Analysis Library#Importance_graph|ImportanceGraph]] ([[The Sensitivity Analysis Library]])
* [[Index Position Operator::@|Index Position Operator: @I, @[I=x] ]] : Get the numeric position of index elements
* [[VarTerm Functions#Function_IndexesOf| IndexesOf]]
* [[Index..Do]]
* [[IndexLength]]
* [[IndexNames]]
* [[IndexValue]]
* [[The Sensitivity Analysis Library#Input Descriptor|InputDescriptors]] ([[The Sensitivity Analysis Library]])
* [[InsertRecSql]] (ODBC Library.ana)
* [[Integer]]
* [[Integrate]]
* [[InvalidateResult]]
* [[InverseGaussian]] (Distribution Variations.ana)
* [[Invert]]
* [[InvertedWishart]] (Distribution Variations.ana)
* [[InvLogit]] (Generalized Regression.ana)
* [[IPmt]]
* [[Irr]]
* [[IsDateTime]]
* [[IsHandle]]
* [[Data_Type_Functions#Function_IsNaN| IsNaN]]
* [[Data_Type_Functions#Function_IsNotSpecified| IsNotSpecified]]
* [[IsNull]]
* [[Data_Type_Functions#Function_IsNumber| IsNumber]]
* [[IsRealNumber]]
* [[Data_Type_Functions#Function_IsReference| IsReference]]
* [[IsResultComputed]]
* [[Data_Type_Functions#Function_IsText| IsText]]
* [[Data_Type_Functions#Function_IsUndef| IsUndef]]
* [[Iterate]]
* [[Join]]
* [[JoinText]]
* [[Keelin]]
* [[KeelinCoefficients]]
* [[Kurtosis]]
* [[LDens_InvertedWishart]] (Distribution Densities.ana)
* [[LDens_Wishart]] (Distribution Densities.ana)
* [[Legendre_kth_root]] ([[Legendre Library]])
* [[LegendreP]] ([[Legendre Library]])
* [[LegendreP_coefs]] ([[Legendre Library]])
* [[LegendreP_deriv]] ([[Legendre Library]])
* [[LGamma]]
* [[LinearInterp]]
* [[ListOfHandles]]
* [[LL_First]] (Linked List Library.ana)
* [[LL_Length]] (Linked List Library.ana)
* [[LL_Nth]] (Linked List Library.ana)
* [[LL_Push]] (Linked List Library.ana)
* [[LL_Remove_First]] (Linked List Library.ana)
* [[LL_To_Array]] (Linked List Library.ana)
* [[LL_to_RArray]] (Linked List Library.ana)
* [[Ln]]
* [[Local Index Operator::A.I]] : Get an index (usually a local index) of an array
* [[Log]]
* [[_Log1p]]
* [[Logistic]]
* [[Logistic_Regression]] (Generalized Regression.ana)
* [[Logit]] (Generalized Regression.ana)
* [[LogNormal]]
* [[Lognormal_m_sd]] (Distribution variations.ana) - obsolete, use [[LogNormal]] (mean:m,stddev:sd)
* [[LogTen]]
* [[Lorenzian]] (Distribution variations.ana)
* [[LpDefine]]
* [[LpFindIIS]]
* [[LpObjSa]]
* [[LpOpt]]
* [[LpRead]]
* [[LpReducedCost]]
* [[LpRhsSa]]
* [[LpShadow]]
* [[LpSlack]]
* [[LpSolution]]
* [[LpStatusNum]]
* [[LpStatusText]]
* [[LpWrite]]
* [[LpWriteIIS]]
* [[MakeCSV]]
* [[Date_Functions#MakeDate.28year.2C_month.2C_day.29| MakeDate]]
* [[MakeJSON]]
* [[MantissaAndExponent]]
* [[MatrixMultiply]]
* [[Functions_Min_and_Max| Max]]
* [[MdArrayToTable]]
* [[MdTable]]
* [[MdxQuery]]
* [[Mean]]
* [[Median]]
* [[MemoryInUseBy]]
* [[Mid]]
* [[Functions_Min_and_Max| Min]]
* [[Mod]]
* [[MonoCubicInterp]]
* [[Move]]
* [[MsgBox]]
* [[MultiChoice]]
* [[Multinomial]] (Multivariate Distributions.ana)
* [[MultiNormal]] (Multivariate Distributions.ana)
* [[MultiTable]]
* [[MultiUniform]] (Multivariate Distributions.ana)
* [[MutableGet]] ([[Mutables library]])
* [[MutableNew]] ([[Mutables library]])
* [[MutableSet]] ([[Mutables library]])
* [[NegBinomial]] (Distribution Variations.ana)
* [[NegativeBinomial]]
* [[NextFloatToward]]
* [[NlpDefine]]
* [[Normal]]
* [[Normal_additive_gro]] (Multivariate Distributions.ana)
* [[Normal_compound_gro]] (Multivariate Distributions.ana)
* [[Normal_correl]] (Multivariate Distributions.ana)
* [[Normal_p1_p2]] ([[:category:Distribution Variations library functions|Distribution Variations.ana]])
* [[Normal_serial_correl]] (Multivariate Distributions.ana)
* [[Normalize]]
* [[Not]]
* [[NPer]]
* [[Npv]]
* [[NumberToText]]
* [[OnDraw_Google_map]] ( [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]] )
* [[OpenExcelFile]] -- deprecated: use [[SpreadsheetOpen]]
* [[OpenModelFile]]
* [[OpenURL]]
* [[OptEngineInfo]]
* [[OptFindIIS]]
* [[OptGuess]]
* [[OptInfo]]
* [[OptObjective]]
* [[OptObjectiveSa]]
* [[OptRead]]
* [[OptReducedCost]]
* [[OptRhsSa]]
* [[OptScalarToConstraint]]
* [[OptScalarToDecision]]
* [[OptShadow]]
* [[OptSlack]]
* [[OptSolution]]
* [[OptStatusNum]]
* [[OptStatusText]]
* [[OptWrite]]
* [[OptWriteIIS]]
* [[Or]]
* [[Pareto]] (Distribution Variations.ana)
* [[ParseCSV]]
* [[ParseDate]]
* [[ParseExpression]]
* [[ParsedExprFunction]]
* [[ParsedExprParameters]]
* [[ParseJSON]]
* [[ParseNum]] (Flat file library.ana - for Analytica 4.1)
* [[ParseNumber]]
* [[Partitions]]
* [[Pdf]]
* [[Permutations]]
* [[Pert]] (Distribution Variations.ana)
* [[Plot_error_bars]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[Plot_point_labels]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[Plot_solid_band]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[Plot_solid_prob_bands]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[Plot_Tukey_bars]] ([[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]])
* [[Pmt]]
* [[Poisson]]
* [[PolarToC]] (Complex Library.ana)
* [[PolyGamma]]
* [[Index Position Operator::@|Position Operator: @I, @[I=x] ]] : Get the numeric position of index elements
* [[PositionInIndex]]
* [[PowerMod]]
* [[PPmt]]
* [[Probability]]
* [[ProbBands]]
* [[ProbDist]]
* [[Probit_Regression]] (Generalized Regression.ana)
* [[ProbTable]]
* [[Prob_Bernoulli]] ([[Distribution Densities Library]])
* [[Prob_Binomial]] ([[Distribution Densities Library]])
* [[Prob_ChanceDist]] ([[Distribution Densities Library]])
* [[Prob_Geometric]] ([[Distribution Densities Library]])
* [[Prob_HyperGeometric]] ([[Distribution Densities Library]])
* [[Prob_NegativeBinomia]] ([[Distribution Densities Library]])
* [[Prob_Poisson]] ([[Distribution Densities Library]])
* [[ProbWilcoxon]]
* [[Product]]
* [[ProductLog]]
* [[Putoption]] (Financial Library.ana)
* [[Pv]]
* [[Pvgperp]] (Financial Library.ana)
* [[Pvperp]] (Financial Library.ana)
* [[QpDefine]]
* [[Q_infromrec]]
* [[Q_makerect]]
* [[Q_squareinterp]]
* [[Radians]]
* [[Random]]
* [[RandomBytes]]
* [[Rank]]
* [[RankCorrel]]
* [[The Sensitivity Analysis Library#Importance Details|RankCorrelDetails]] ([[The Sensitivity Analysis Library]])
* [[Rate]]
* [[Rayleigh]] (Distribution variations.ana)
* [[Re]] (Complex Library.ana)
* [[ReadBinaryFile]]
* [[ReadCsvFile]]
* [[ReadExportFile]]
* [[ReadFromUrl]]
* [[ReadImageFile]]
* [[ReadTextFile]]
* [[RealPart]]
* [[Reference Operator::\|Reference Operator: \X]] : Return a reference to X
* [[Reform]]
* [[Regression]]
* [[RegressionDist]] (Multivariate Distributions.ana)
* [[RegressionFitProb]] (Multivariate Distributions.ana)
* [[RegressionNoise]] (Multivariate Distributions.ana)
* [[Relu]]
* [[ReThrow]]
* [[Reverse]]
* [[Round]]
* [[RunConsoleProcess]]
* [[Sample]]
* [[SampleCorrelation]] (Multivariate Distributions.ana)
* [[SampleCovariance]] (Multivariate Distributions.ana)
* [[SaveExcelWorkbook]] -- deprecated: use [[SpreadsheetSave]]
* [[ScanAttFromModelFile]]
* [[SchedulePublish]]
* [[SDeviation]]
* [[SelectText]]
* [[The Sensitivity Analysis Library#Input Number|SensitivityIndex]] ([[The Sensitivity Analysis Library]])
* [[Sequence]]
* [[Sequence Operator|Sequence Operator: first..last]]
* [[SetContains]]
* [[SetDifference]]
* [[SetEvaluationFlag]]
* [[SetIntersection]]
* [[SetUnion]]
* [[ShowAskAttribute]]
* [[ShowPdfFile]]
* [[ShowProgressBar]]
* [[ShowWindow]]
* [[Shuffle]]
* [[Sign]]
* [[Trig Functions| Sin]]
* [[SingularValueDecomp]]
* [[Trig Functions| Sinh]]
* [[SipDecode]]
* [[SipEncode]]
* [[Size]]
* [[Skewness]]
* [[Sleep]]
* [[Slice]]
* [[Slider]]
* [[Subscript/Slice Operator| Slice Operator: [@I=n] ]]
* [[Smooth_Fractile]] (Distribution variations.ana)
* [[SobolSequence]]
* [[Solve]] (Optimization Functions.ana)
* [[SolverInfo]]
* [[Sort]]
* [[SortIndex]]
* [[Split]]
* [[SplitText]]
* [[SpreadsheetCell]]
* [[SpreadsheetInfo]]
* [[SpreadsheetOpen]]
* [[SpreadsheetRange]]
* [[SpreadsheetSave]]
* [[SpreadsheetSetCell]]
* [[SpreadsheetSetInfo]]
* [[SpreadsheetSetRange]]
* [[SqlDriverInfo]]
* [[Sqr]]
* [[Sqrt]]
* [[Statistics]]
* [[StepInterp]]
* [[StringLength]]
* [[StringLowercase]]
* [[StringMixedCase]]
* [[StringReplace]]
* [[StringUpperCase]]
* [[StudentT]]
* [[SubFindString]]
* [[SubIndex]]
* [[Subscript]]
* [[Subscript/Slice Operator| Subscript Operator: [I=x] ]]
* [[Subset]]
* [[SubString]]
* [[SubTable]]
* [[Sum]]
* [[The Sensitivity Analysis Library#Importance Details|SWRSensDetails]] ([[The Sensitivity Analysis Library]])
* [[Sys_coordindex]]
* [[Sys_localindex]]
* [[SysMenu_AddItem]]
* [[Table]]
* [[TableJoin]]
* [[Trig Functions| Tan]]
* [[Trig Functions| Tanh]]
* [[Test_map_pivot_slice]] ( [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]] )
* [[Test_map_pivot_vars]] ( [[:Category:Google Maps from OnGraphDraw library functions|Google Maps from OnGraphDraw library]] )
* [[TestHeapConsistency]]
* [[TextCharacterEncode]]
* [[Text Concatenation Operator: &|Text Concatenation Operator: A&B]] : Concatenate two text strings
* [[TextDistance]]
* [[TextLength]]
* [[TextLowerCase]]
* [[TextReplace]]
* [[TextSentenceCase]]
* [[TextTrim]]
* [[TextUpperCase]]
* [[Today]]
* [[_TrackAttChanges]]
* [[Transpose]]
* [[Triangular]]
* [[Triangular_10_50_90]] (Distribution Variations.ana)
* [[Triangular_10_mode_90]] (Distribution Variations.ana)
* [[Truncate]]
* [[Try]]
* [[Data_Type_Functions#Function_TypeOf| TypeOf]]
* [[UncertainLMH]]
* [[Uncumulate]]
* [[Unflatten]]
* [[Uniform]]
* [[UniformSpherical]] (Multivariate distributions.ana)
* [[Unique]]
* [[Using..Do]]
* [[Var..Do]]
* [[Variance]]
* [[VarTerm]]
* [[VectorCrossProduct]]
* [[Expected value of information -- EVI, EVPI, and ESVI#Function VPI(v, d)|VPI]] ([[Expected value of information -- EVI, EVPI, and ESVI|Value of Information library]])
* [[Wacc]] (Financial Library.ana)
* [[Wald]] (Distribution Variations.ana)
* [[Warp_Dist]] (Distribution variations.ana)
* [[_WebConnectionClose]]
* [[_WebConnectionRead]]
* [[_WebConnectionSend]]
* [[_WebConnectionStatus]]
* [[Weibull]]
* [[WhatIf]]
* [[WhatIfAll]]
* [[While..Do]]
* [[Wilcoxon]]
* [[Wishart]] (Distribution variations.ana)
* [[WorksheetCell]] -- deprecated: use [[SpreadsheetCell]]
* [[WorksheetRange]] -- deprecated: use [[SpreadsheetRange]]
* [[WriteBinaryFile]]
* [[WriteCsvFile]]
* [[WriteImageFile]]
* [[WriteTableSql]] (ODBC Library.ana)
* [[WriteTextFile]]
* [[WriteWorksheetCell]] -- deprecated: use [[SpreadsheetSetCell]]
* [[WriteWorksheetRange]] -- deprecated: use [[SpreadsheetSetRange]]
* [[XIrr]]
* [[XNpv]]
* [[YearFrac]]

RandomBytes

2026-09-22T17:41:51Z

Lchrisman: ER 22440: point the redirect at the function-reference anchor

#REDIRECT [[Encrypting and decrypting#RandomBytes]]
[[category:Encrypting and hashing functions]]

Decrypt

2026-09-22T17:41:51Z

Lchrisman: ER 22440: point the redirect at the function-reference anchor

#REDIRECT [[Encrypting and decrypting#Decrypt]]
[[category:Encrypting and hashing functions]]

Encrypt

2026-09-22T17:41:51Z

Lchrisman: ER 22440: point the redirect at the function-reference anchor

#REDIRECT [[Encrypting and decrypting#Encrypt]]
[[category:Encrypting and hashing functions]]

EncryptionKey

2026-09-22T17:41:51Z

Lchrisman: ER 22440: point the redirect at the function-reference anchor

#REDIRECT [[Encrypting and decrypting#EncryptionKey]]
[[category:Encrypting and hashing functions]]

Encrypting and decrypting

2026-09-22T17:41:28Z

Lchrisman: ER 22440: document the Crypto namespace -- EncryptionKey, Encrypt, Decrypt, RandomBytes, key->Export()

[[category:Encrypting and hashing functions]]

{{ReleaseBar}}

''New to [[Analytica 7.2]].''

Analytica can encrypt and decrypt data using strong, standard, ''authenticated'' encryption. The four functions live in the '''<code>Crypto</code>''' namespace:

* [[#EncryptionKey|Crypto::EncryptionKey]] -- makes a key, which is a value of its own data type.
* [[#Encrypt|Crypto::Encrypt]] -- seals text or binary data under a key.
* [[#Decrypt|Crypto::Decrypt]] -- opens a sealed value, or reports an error if anything about it has changed.
* [[#RandomBytes|Crypto::RandomBytes]] -- cryptographically random bytes, for salts and keys.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] MyKey := Crypto::EncryptionKey( password: 'correct horse battery staple', salt: Salt )</code>
: <code>[[Variable]] Sealed := Crypto::Encrypt( 'launch codes', MyKey )</code>
: <code>[[Variable]] Plain := Crypto::Decrypt( Sealed, MyKey ) → 'launch codes'</code>

== The Crypto namespace ==

These are specialist functions, so they are not in your model's namespace to begin with. A model that never encrypts anything is not troubled by them, and they cannot collide with your own identifiers. You reach them in either of two ways.

'''Qualify each call''' with <code>Crypto::</code>, as in the example above. Nothing is needed to make this work.

'''Or import the namespace once.''' Put <code>Crypto</code> on a line of its own in your model's [[NamespaceImports]] attribute, and then write the names bare:

: <code>Encrypt( 'launch codes', MyKey )</code>

The rest of this page writes <code>Crypto::</code> explicitly so that each example works whether or not you have imported the namespace.

== What authenticated encryption means ==

All four algorithms here are ''AEAD'' ciphers -- Authenticated Encryption with Associated Data. Along with the encrypted data, a sealed value carries an ''authentication tag'' computed from the key. [[#Decrypt|Crypto::Decrypt]] checks the tag before it returns anything, so a sealed value that has been altered -- even by a single bit, even by someone who cannot read it -- produces an error instead of altered data.

This is what you want, and it is not what simpler schemes give you. Encryption on its own hides data but does not stop an attacker from changing it in ways that change the decrypted result predictably. Nothing on this page lets you do unauthenticated encryption, deliberately.

The error from a failed decryption is deliberately the same whether the key was wrong, the «aad» was wrong, or the data was altered. Telling those cases apart would help an attacker work out a key one guess at a time.

== Keys ==

A key is a value of its own type, made by [[#EncryptionKey|Crypto::EncryptionKey]]. It carries the algorithm along with the key material, so a key and an algorithm can never disagree, and [[#Encrypt|Crypto::Encrypt]] needs no «algorithm» parameter.

'''Make the key its own variable.''' Deriving a key from a password takes a noticeable fraction of a second by design (see [[#Passwords and salts|Passwords and salts]]). When the key is a variable, Analytica computes it once and reuses it, so encrypting a whole column of a table costs one derivation, not one per cell. Writing the derivation inline inside [[#Encrypt|Crypto::Encrypt]] would repeat it for every cell.

The key material itself cannot be read from any expression. Printing a key shows only what it is:

: <code>MyKey → «EncryptionKey AES-256-GCM #7a2f»</code>

A key has four readable members:

* <code>MyKey->algorithm</code> -- <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>.
* <code>MyKey->keyBits</code> -- 128, 192 or 256.
* <code>MyKey->fingerprint</code> -- four hexadecimal digits that identify the key without revealing it. Two keys are the same key if and only if their fingerprints match (to a very high probability). Useful for answering "did this deployment get the key I think it did?" without ever displaying a key.
* <code>MyKey->fromSecret</code> -- [[True]] when the key material came from a [[Secret]].

=== Passwords and salts ===

<code>Crypto::EncryptionKey( password: p, salt: s )</code> stretches a password into a key using PBKDF2-HMAC-SHA-256 with «iterations» rounds, 600,000 by default. The iterations are the point: they make each guess at your password expensive for an attacker, which is the only defence a human-chosen password has.

The «salt» is '''not''' secret. Keep it in an ordinary variable next to the key, and save it with your model -- you need the same salt to derive the same key again. Its job is to make precomputed attack tables useless, which it does even though it is public. Make one with <code>[[#RandomBytes|Crypto::RandomBytes]](16)</code> and then leave it alone; changing the salt changes the key, and data encrypted under the old key can no longer be read.

=== Keeping the key out of the model ===

If the key is written in the model, anyone who has the model has the key, and the encryption protects nothing. The usual arrangement is the other way round: the ''sealed data'' travels in the <code>.ana</code> file and the ''key'' does not.

Give «key» or «password» a [[Secret]] to do that. The secret's value reaches the key derivation without ever entering the model as a value:

: <code>Crypto::EncryptionKey( key: MyKeySecret )</code>
: <code>Crypto::EncryptionKey( password: MyPasswordSecret, salt: Salt )</code>

The [[Secret]] needs two things set before Analytica will allow this:

* '''Sinks''' must list <code>EncryptionKey</code>.
* '''Destination''' must be the single word <code>local</code>. Unlike a URL or a database connection string, key material never leaves the Analytica process, so there is no destination to pin -- but the setting is still required, so that allowing it is a deliberate act.

Consider also setting the secret's '''Caller''' to the module that is allowed to build the key, which restricts the use of the secret far more tightly than any destination could.

A key made from a [[Secret]] refuses <code>->Export()</code>, and reads <code>fromSecret = True</code>. That is deliberate: a secret's value must never come back into the model, and exporting the key it produced would be exactly that.

=== Generating and saving a key ===

<code>Crypto::EncryptionKey()</code> with no arguments makes a fresh random key. To use the same key again later, export the material and store it somewhere outside the model -- a [[Secret]], a file, a password manager:

: <code>Crypto::EncryptionKey()->Export() → a 32-byte binary value</code>

To see it as text you can copy, format it:

: <code>f"{Crypto::EncryptionKey()->Export():b}" → base64'8Xk2wQ...'</code>

Paste that <code>base64'...'</code> literal back into an expression to rebuild the same key:

: <code>Crypto::EncryptionKey( key: base64'8Xk2wQ...' )</code>

'''A key cannot be stored in a variable''' the way other values can. Assigning one to a variable's definition is refused, because that would write the key material into the <code>.ana</code> file. Build the key where it is used instead.

== Sealed values ==

[[#Encrypt|Crypto::Encrypt]] returns [[In-memory binary data terms|binary data]] by default. The <code>'analytica'</code> container adds 36 bytes to whatever you encrypted: a marker that says this is an Analytica sealed value, which algorithm made it, whether the plaintext was text or binary, the nonce, and the authentication tag.

Because the container records whether the plaintext was text or binary, [[#Decrypt|Crypto::Decrypt]] hands back the same kind of value you encrypted, with nothing extra to say.

=== Every call produces a different result ===

Each call draws a fresh random ''nonce'', so encrypting the same text twice gives two different sealed values. That is required -- reusing a nonce with the same key breaks the encryption completely -- but it has a practical consequence in a model: a sealed value computed by a definition changes every time the definition is re-evaluated.

So do not leave <code>Crypto::Encrypt(...)</code> in the definition of a variable whose result you intend to keep. Compute the sealed value once, in a button script, and assign it:

: <code>Sealed := Crypto::Encrypt( Plaintext, MyKey )</code>

The assignment writes the sealed value into <code>Sealed</code>'s definition as a <code>base64'...'</code> literal, which is saved with the model and decrypts unchanged when it is reopened.

=== Binding a sealed value to its context ===

The optional «aad» parameter -- additional authenticated data -- is authenticated but not encrypted. Whoever decrypts must supply the same «aad» or the decryption fails.

Use it to tie each sealed value to where it belongs. If you seal a column of salaries with no «aad», someone who cannot read them can still swap two rows and go undetected. Seal them with the employee as «aad» and the swap is caught:

: <code>Crypto::Encrypt( Salary, MyKey, aad: Employee )</code>
: <code>Crypto::Decrypt( SealedSalary, MyKey, aad: Employee )</code>

The «aad» is not secret and does not need to be hidden -- the reader has to know it anyway.

== Encrypting a whole table ==

«data» and «aad» are atomic parameters, so both functions [[Array Abstraction|array abstract]]. One expression seals an entire indexed table, each cell under its own fresh nonce, all under the one key:

: <code>[[Variable]] SealedRows := Crypto::Encrypt( PlainRows, MyKey )</code>
: <code>[[Variable]] PlainAgain := Crypto::Decrypt( SealedRows, MyKey )</code>

This is where making the key its own variable pays off: the key is derived once and every cell reuses it.

== Interoperating with other systems ==

To exchange sealed data with something outside Analytica, you need to agree on two things: how the bytes are packaged, and how they are written as text.

=== Layouts ===

There is no single universal convention for packaging a nonce, a ciphertext and an authentication tag, so «layout» lets you pick the one your counterpart uses.

{| class="wikitable"
! «layout» !! The sealed value contains !! Used by
|-
| <code>'analytica'</code> (default) || A self-describing container: marker, algorithm, text-or-binary flag, nonce, tag, ciphertext || Analytica
|-
| <code>'nonce,ct,tag'</code> || nonce, then ciphertext, then tag || The common Go idiom, and most published examples
|-
| <code>'ct,tag'</code> || ciphertext, then tag; the nonce is separate || Python's <code>cryptography</code> package, libsodium
|-
| <code>'nonce,tag,ct'</code> || nonce, then tag, then ciphertext ||
|-
| <code>'none'</code> || the bare ciphertext; nonce and tag are separate || Node.js <code>crypto</code>, .NET <code>AesGcm</code>
|}

Whatever the layout, the nonce and the tag are '''also''' available as the second and third return values, so you can always get at them:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

and supply them again when decrypting a layout that does not carry them:

: <code>Crypto::Decrypt( ct, MyKey, nonce: n, tag: t, layout: 'none', as: 'text' )</code>

The raw layouts carry no record of whether the plaintext was text or binary, so «as» is required with them.

=== Text encodings ===

«format» writes the sealed value as text instead of binary data -- <code>'base64'</code>, <code>'base64url'</code> (the URL-safe alphabet, no padding) or <code>'hex'</code>. [[#Decrypt|Crypto::Decrypt]] reads text in the same encodings.

: <code>Crypto::Encrypt( 'hello', MyKey, format: 'base64' )</code>
: <code>Crypto::Decrypt( sealedText, MyKey, format: 'base64' )</code>

=== A worked example ===

This Python produces a value Analytica reads, and reads a value Analytica produced. It uses the <code>cryptography</code> package.

<pre>
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64

key = bytes(range(32)) # the same 32 bytes as base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8='
nonce = bytes(range(12))

# Seal something for Analytica
ct = AESGCM(key).encrypt(nonce, 'from python'.encode('utf-8'), b'ctx7')
print(base64.b64encode(nonce + ct).decode())

# Open something Analytica sealed with layout:'ct,tag'
plain = AESGCM(key).decrypt(nonce, bytes.fromhex('66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'), None)
print(plain.decode('utf-8')) # -> hello
</pre>

In Analytica:

: <code>[[Variable]] K := Crypto::EncryptionKey( key: base64'AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=' )</code>
: <code>Crypto::Decrypt( base64'AAECAwQFBgcICQoLIXC5duWVu2/lLvmrU3Xrc1+3jRqJx0hC/3QKjDlK2w==', K, layout: 'nonce,ct,tag', aad: 'ctx7', as: 'text' ) → 'from python'</code>
: <code>Crypto::Encrypt( 'hello', K, nonce: base64'AAAAAAAAAAAAAAAA', layout: 'ct,tag', format: 'hex' ) → '66d9d9b2da0e0c4679f3a82524f5e0499271e16f30'</code>

The «nonce» parameter is used here only to make the output reproducible so it can be checked against a published test vector. '''Do not supply a nonce in real use.''' Reusing a nonce with the same key destroys the security of the encryption completely; omitting it is always the right thing.

=== The 'analytica' container ===

If you need to read Analytica's own container from another language, its bytes are:

{| class="wikitable"
! Offset !! Length !! Field
|-
| 0 || 4 || The four characters <code>ACRY</code>
|-
| 4 || 1 || Format version, currently 1
|-
| 5 || 1 || Algorithm: 1 = AES-128-GCM, 2 = AES-192-GCM, 3 = AES-256-GCM, 4 = ChaCha20-Poly1305
|-
| 6 || 1 || Flags. Bit 0 set means the plaintext was text, encoded as UTF-8. Bit 1 set means an «aad» was supplied.
|-
| 7 || 1 || Nonce length, 12 for every algorithm above
|-
| 8 || 12 || Nonce
|-
| 20 || 16 || Authentication tag
|-
| 36 || rest || Ciphertext
|}

The salt and the iteration count are '''not''' in the container. They belong to the key, which you construct explicitly, so keep the salt in a variable of your own next to the key that uses it.

= Function reference =

<span id="EncryptionKey"></span>
== Crypto::EncryptionKey( algorithm, key, keyFormat, password, salt, iterations, kdf ) ==

Creates a key for [[#Encrypt|Crypto::Encrypt]] and [[#Decrypt|Crypto::Decrypt]]. Give it either «key» or «password», or neither for a fresh random key.

=== Parameters ===

* «algorithm»: (optional, default <code>'AES-256-GCM'</code>) One of <code>'AES-256-GCM'</code>, <code>'AES-192-GCM'</code>, <code>'AES-128-GCM'</code> or <code>'ChaCha20-Poly1305'</code>. ChaCha20-Poly1305 requires Windows 10 version 1903 or later; on an older system it reports that it is unavailable rather than failing obscurely.

* «key»: (optional) Raw key material, as [[In-memory binary data terms|binary data]] -- usually a <code>base64'...'</code> literal. It must be exactly the algorithm's key length: 32 bytes for AES-256-GCM and ChaCha20-Poly1305, 24 for AES-192-GCM, 16 for AES-128-GCM. A key of the wrong length is an error; Analytica will not pad or hash it to fit, because that would quietly weaken it. You may also pass a [[Secret]] here, in which case the secret's text is decoded according to «keyFormat». Plain text that is not a [[Secret]] is refused -- use «password» for a passphrase.

* «keyFormat»: (optional, default <code>'base64'</code>) How to read the text a [[Secret]] holds: <code>'base64'</code>, <code>'base64url'</code>, <code>'hex'</code> or <code>'utf8'</code>. Meaningful only when «key» is given a [[Secret]].

* «password»: (optional) A passphrase to derive the key from. Requires «salt». May be given a [[Secret]].

* «salt»: (optional) Text or [[In-memory binary data terms|binary data]], at least 8 bytes, required whenever «password» is given. Not secret; see [[#Passwords and salts|Passwords and salts]].

* «iterations»: (optional, default 600000) PBKDF2 rounds. More is slower and safer. Use the same number every time, or you get a different key.

* «kdf»: (optional, default <code>'PBKDF2-HMAC-SHA-256'</code>) The key-derivation function. This release supports only that one; the parameter exists so that adding others later does not change how you write the call.

A parameter that could not take effect is refused rather than quietly ignored -- «iterations» without «password», for example.

=== Members ===

<code>->algorithm</code>, <code>->keyBits</code>, <code>->fingerprint</code> and <code>->fromSecret</code>, described under [[#Keys|Keys]]. There is no member that returns the key material.

<span id="Export"></span>
== key->Export( ) ==

Returns the raw key material of a key as [[In-memory binary data terms|binary data]]. This is the only way to get key material back out, and it is meant for saving a randomly generated key so the same key can be used again.

: <code>MyKey->Export() → a 32-byte binary value</code>

A key derived from a [[Secret]] cannot be exported, and reports an error. A secret's value is never allowed back into the model.

<span id="Encrypt"></span>
== Crypto::Encrypt( data, key, aad, nonce, format, layout ) ==

Encrypts «data» under «key» and returns a sealed value that only the same key can open. Returns [[Null]] when «data» is [[Null]].

=== Parameters ===

* «data»: Text or [[In-memory binary data terms|binary data]]. A number is refused rather than converted, since <code>42</code> could reasonably mean either the text <code>'42'</code> or eight bytes -- use <code>[[Text]](x)</code> if you mean its textual form.

* «key»: A key from [[#EncryptionKey|Crypto::EncryptionKey]]. The algorithm comes from the key.

* «aad»: (optional) Additional authenticated data -- authenticated but not encrypted. [[#Decrypt|Crypto::Decrypt]] must be given the same value. See [[#Binding a sealed value to its context|Binding a sealed value to its context]].

* «nonce»: (optional, named) Supplies the nonce instead of generating one. '''Reusing a nonce with the same key destroys the security of the encryption completely.''' Omit this unless you are reproducing a published test vector or another system's exact output.

* «format»: (optional, named, default <code>'binary'</code>) <code>'binary'</code>, <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>.

* «layout»: (optional, named, default <code>'analytica'</code>) See [[#Layouts|Layouts]].

=== Return value ===

The sealed value, as [[In-memory binary data terms|binary data]] or as text according to «format». The nonce and the authentication tag are returned as the second and third return values:

: <code>[[Local]] (sealed, nonce, tag) := Crypto::Encrypt( x, MyKey );</code>

It [[Array Abstraction|array abstracts]] over «data» and «aad», sealing each cell under its own nonce.

<span id="Decrypt"></span>
== Crypto::Decrypt( data, key, aad, nonce, tag, format, layout, as ) ==

Opens a value sealed by [[#Encrypt|Crypto::Encrypt]]. Returns [[Null]] when «data» is [[Null]].

Reports an error if the value cannot be decrypted -- wrong key, wrong «aad», or data that has been altered. The message deliberately does not say which, because that distinction would help an attacker. Use [[Try]] if your model should carry on regardless.

=== Parameters ===

* «data»: The sealed value, as [[In-memory binary data terms|binary data]], or as text in the encoding named by «format».

* «key»: The same key the value was sealed with. If it is a key for a different algorithm, that is reported specifically, since it is a mistake you can act on rather than a failed decryption.

* «aad»: (optional) Must equal the «aad» the value was sealed with.

* «nonce», «tag»: (optional, named) Required for a «layout» that does not carry them.

* «format»: (optional, named, default <code>'base64'</code>) How to read a textual «data»: <code>'base64'</code>, <code>'base64url'</code> or <code>'hex'</code>. Ignored when «data» is binary.

* «layout»: (optional, named, default <code>'analytica'</code>) Must match the layout the value was sealed with. See [[#Layouts|Layouts]].

* «as»: (optional, named) <code>'text'</code> or <code>'binaryData'</code>. With the default <code>'analytica'</code> layout it is optional, because the sealed value records which one was encrypted. For every other layout it is required. <code>'text'</code> reports an error if the decrypted bytes are not valid UTF-8, which is usually a sign that you wanted <code>'binaryData'</code>.

<span id="RandomBytes"></span>
== Crypto::RandomBytes( n ) ==

Returns «n» cryptographically random bytes as [[In-memory binary data terms|binary data]]. Use it for a «salt», or for raw key material.

: <code>[[Variable]] Salt := Crypto::RandomBytes(16)</code>
: <code>[[Variable]] NewKey := Crypto::EncryptionKey( key: Crypto::RandomBytes(32) )</code>

«n» may not exceed 65536.

Each evaluation returns different bytes. Like [[#Encrypt|Crypto::Encrypt]], this means a definition that calls it does not hold still across re-evaluations -- assign the result once if you need it to stay the same.

== Errors ==

Most mistakes are reported specifically, and can be caught with [[Try]]:

* The «key» is the wrong length for the algorithm, or «key» was given plain text rather than key material or a [[Secret]].
* Both «key» and «password» were given, or «password» was given without a «salt», or a parameter such as «iterations» cannot take effect.
* The algorithm is not one of the four, or is not available on this computer.
* «data» is a number rather than text or binary data.
* The sealed value is not an Analytica sealed value, or was sealed with a different algorithm, or the text is not valid for the stated «format».
* A [[Secret]] was passed where a secret makes no sense, such as «aad» or «salt», neither of which is secret.
* <code>->Export()</code> was called on a key derived from a [[Secret]].

The one deliberately vague error is a failed decryption, described under [[#Decrypt|Crypto::Decrypt]].

== See Also ==

* [[Secret]] -- keeping a key out of the model
* [[TextCharacterEncode]] -- hashing text with SHA-1 or SHA-256, and other text encodings
* [[In-memory binary data terms]]
* [[NamespaceImports]]
* [[:category:Encrypting and hashing functions|Encrypting and hashing functions]]

Category:Encrypting and hashing functions

2026-09-22T17:05:04Z

Lchrisman:

[[category:Functions]]
Functions used for encryption, decryption, hashing or other cryptographic purposes.

TextCharacterEncode

2026-09-22T17:04:21Z

Lchrisman: category hashing

[[category:Text Functions]]
[[category:Analytica 5.0]]
[[category:Encrypting and hashing functions]]

{{ReleaseBar}}
(''new to [[Analytica 5.0]]'')

Converts text to or from many common codings, including URLs, XML, UTF-i, and NFC (unicode).

== TextCharacterEncode( type, text ) ==

Converts «text» into a special encoded or unencoded form according to «type». Possible values for «type» include:

* For encoding or decoding URLs: <code>'URL'</code>, <code>'IRI'</code>, <code>'URL%'</code>, <code>'-URL'</code>
* For encoding XML or HTML: <code>'XML'</code>, <code>'-XML'</code>
* For UTF-8 encodings: <code>'UTF-8'</code>, <code>'UTF-8+'</code>, <code>'-UTF-8'</code>
* For Unicode normalized forms: <code>'NFC'</code>, <code>'NFD'</code>, <code>'NFKC'</code>, <code>'NFKD'</code>.{{Release|6.5||
* Hash code: <code>'SHA-1'</code>, <code>'SHA-256'</code>}}
* Return «text» with no change: <code>'None'</code>{{Release|6.3||
* [[Entering extended characters|Unicode character names]]: <code>'characterName'</code>, <code>'-characterName'</code>}}

Start «type» with a minus, code>'-'</code>, to invert the encoding -- i.e. to decode the text.

== Encoding text for inclusion in a URL ==

«Type» options <code>'URL'</code>, <code>'IRI'</code> and <code>'URL%'</code> encode data for inclusion on a URL. The option <code>'-URL'</code> decodes URL data.

Data is often passed in the query string portion of a URL, such as "John Doe" in the following URL:
::<code>http://acme.com/somePage?name=John+Doe</code>
Notice that it converts the space to a <code>'+'</code> before inserting it in the URL. The special characters "<code>"!*'();:@&=+$,/?#[]%</code> each have a special meaning in a URL and so must be converted into text that does not involve those characters. The «type» value <code>'URL'</code> encodes data according to the RFC-3986 standard.

If you ever need to pass a URL as a data item in another URL, you must encode all its special characters so they aren't interpreted as part of the outer URL.

This same encoding appears in other standards as well, including submitting form data in HTTP, and in for JSON.

When using <code>[[TextCharacterEncode]]('URL', text)</code>, your text should only encode the value that will be placed after an equal sign in the query, but nothing more. For example, you should write:
::<code>'http://acme.com/somePage?name=' & [[TextCharacterEncode]]( 'URL', 'John Doe' )</code>
not
::<code>[[TextCharacterEncode]]( 'URL', 'http://acme.com/somePage?name=John Doe' )</code>
since in the latter case the characters <code>? =:/</code>, etc. will be encoded, which you don't want.

A problem with the <code>'URL'</code> encoding is that all characters except the letters, digits, and <code>-._~</code> are percent encoded, making URLs very difficult to read, especially for non-English sites. The <code>'IRI'</code> option (International Resource Identifier) preserves all but the reserved characters ("<code>!*'();:@&=+$,/?#[]%</code>"), which generally still works correctly for URLs.

The standard URL encoding changes space to a plus character. The <code>'URL%'</code> option uses percent encoding for space (<code>%20</code>) instead.

The «type» option <code>'-URL'</code> converts the URL-encoded text back into the original text. It works for any of the encodings <code>'URL'</code>, <code>'IRI'</code> and <code>'URL%'</code>.

=== Examples ===

:<code>[[TextCharacterEncode]]('URL', '(1+2) = 3') → "%281%2B2%29+%3D+3"</code>
:<code>[[TextCharacterEncode]]('URL%', '(1+2) = 3') → "%281%2B2%29%20%3D%203"</code>
:<code>[[TextCharacterEncode]]('-URL','%281%2B2%29+%3D+3') → "(1+2) = 3"</code>
:<code>[[TextCharacterEncode]]('-URL','%281%2B2%29%20%3D%203') → "(1+2) = 3"</code>
:<code>[[TextCharacterEncode]]('URL', 'test@中文.com') → "test%40%E4%B8%AD%E6%96%87.com"</code>
:<code>[[TextCharacterEncode]]('IRI', 'test@中文.com') → "test%40中文.com"</code>

:Variable email := <code>"John_Doe@yahoo.com"</code>
:Variable website := <code>"http://acme.com?name=johnDoe&type=student"</code>
:Variable cityToFind = <code>"San Francisco, CA"</code>
:Variable UrlToRead := <code>"http://dataSource.com/query?email=" & [[TextCharacterEncode]]( 'URL', email ) & "&site=" & [[TextCharacterEncode]]('URL', website) & "&city=" & [[TextCharacterEncode]]('URL', cityToFind)</code>
::: <code>UrlToRead</code> → <code>"http://dataSource.com/query?email=John_Doe%40yahoo.com&site=http%3A%2F%2Facme.com%3Fname%3DjohnDoe%26type%3Dstudent&city=San+Francisco%2C+CA"</code>

== Encoding text in XML or HTML ==

The option <code>'XML'</code> for «type» encodes data for insertion in XML or HTML. Without this encoding, an XML or HTML parser will attempt to interpret special characters such as '<', '>', '&', quotes. Also, a few characters falling in control ranges (below ascii 32 or between ascii 128 and 159) will be automatically converted to entities as required be the standards.

The <code>'-XML'</code> does the inverse decoding.

{{Release|6.3||
== Character names ==
''New to [[Analytica 6.3]]''

You can map an extended character to its name, or a character name to the character, for example:
:<code>[[TextCharacterEncode]]( 'Ψ', 'characterName')</code> → <code>'Psi'</code>
:<code>[[TextCharacterEncode]]( 'Psi', '-characterName'</code> → <code>'Ψ'</code>
You can use these character names when [[Entering extended characters|typing extended characters]] by typing a backslash, <code>\</code>, the character name, then the TAB key.

When a character has no special name assigned, <code>[[TextCharacterEncode]]( 'Ψ', 'characterName')</code> returns [[Null]]. Analytica reads the character names from the file <code>"characterNames.ini"</code> found in the Analytica installation folder.
}}

=== Examples ===

:<code>[[TextCharacterEncode]]( 'XML', 'One < Two, <b>Three & Four</b> are "Bigger"' ) </code>
:::→ <code>"One &lt; Two, &lt;b&gt;Three &amp; Four&lt;/b&gt; are &quot;Bigger&quot;"</code>
:<code>[[TextCharacterEncode]]('-XML', One &lt; Two, &lt;b&gt;Three &amp; Four&lt;/b&gt; are &quot;Bigger&quot;' )</code>
::: → <code>'One < Two, <b>Three & Four</b> are "Bigger"'</code>

== UTF-8 encoding ==

Set «type» to <code>'UTF-8'</code> to obtain the UTF-8 encoding, or to <code>'-UTF-8'</code> to decode a UTF-8 encoding into the Unicode characters.

The option <code>'UTF-8+'</code> prepends the UTF-8 ''Byte Order Mark'' (BOM). The <code>'-UTF-8'</code> decoding option always removes the BOM if it is present.

=== Examples ===
:<code>[[TextCharacterEncode]]('UTF-8', '확률 분포') → "íë¥ ë¶í¬"</code>
:<code>[[Asc]]([[SplitText]]([[TextCharacterEncode]]('UTF-8', '확률 분포')))</code>
:::→ <code>[0xed, 0x99, 0x95, 0xeb, 0xa5, 0xa0, 0x20, 0xeb, 0xb6, 0x84, 0xed, 0x8f, 0xac]</code>
:<code>[[TextCharacterEncode]]('-UTF-8', 'íë¥ ë¶í¬') → "확률 분포"</code>
:<code>[[TextCharacterEncode]]('UTF-8+', '확률 분포') → "ï»¿íë¥ ë¶í¬"</code> { <code>'ï»¿'</code> is the BOM }

== Unicode normalization ==

The «type» options <code>'NFC'</code>, <code>'NFD'</code>, <code>'NFKC'</code>, and <code>'NFKD'</code> convert text into canonical Unicode normalized forms.

The [http://www.unicode.org/standard/principles.html Unicode standard] includes special ''combining'' characters that allow ' ''composite character'' to be constructed from one or more combining characters applied to a main character. As a result, there are often multiple ways to encode the same visible glyph, which is often the case with accented characters. For example, the accented 'a' character <code>'á'</code> can be obtained with either of the following:

:<code>[[Chr]](225) → 'á'</code>
:<code>'a' & [[Chr]](0x301) → 'á' </code>

Although these display the same, the first has a [[TextLength|text length]] of 1, the second a text length of 2. The character <code>[[Chr]](0x301)</code> is the acute accent combining character, and can be applied to any character. In fact, it is even possible to apply multiple combining characters to the same glyph.

When you want to ensure that combined characters are used (such as the one character <code>'á'</code>), set «type» to <code>'NFC'</code>, which stands for ''Normalized Form Combined''. If the two character sequence <code>'a' & [[Chr]](0x301)</code> appears in «text», it will be replaced with the single pre-composed character <code>[[Chr]](225)</code>.

When you want to ensure that composite characters are split into individual combining character constituents, set «type» to <code>'NFD'</code>, which stands for ''Normal Form Decomposed''. Hence, for example, the single character <code>'á'</code> will be replaced with the two character sequence :<code>'a' & [[Chr]](0x301)</code>.

Unicode also includes digraph [https://en.wikipedia.org/wiki/List_of_precomposed_Latin_characters_in_Unicode ligature characters]], such as the ligature <code>'ﬁ'</code>, which is a single character glyph that contains both <code>'f'</code> and <code>'i'</code>. The «type» options <code>'NFKC'</code> and <code>'NFKD'</code> expand ligatures and digraphs into their individual characters. None of the four canonical Unicode encodings re-combine character sequences into pre-composed ligatures.

Note: The four Unicode normalization encodings required Windows Vista or later. When running on XP, «text» is returned unchanged.

{{Release|6.5||
== Hash codes ==
''New to [[Analytica 6.5]]''

The <code>'SHA-1'</code> hash returns a 40 hexadecimal character string and <code>'SHA-256'</code> hash returns a 64 hexadecimal character string. These can be used to verify that text from two sources is the same. It is a standard used in various cryptographic contexts. <code>'SHA-1'</code> is considered as not very secure since being cryptographically broken. However, it is still widely used, for example by the 2-factor authentication standard that uses authenticator apps for the second form of authentication.

:<code>[[TextCharacterEncode]]( 'SHA-1', 'Hello world') → '7b502c3a1f48c8609ae212cdfb639dee39673f5e'</code>
:<code>[[TextCharacterEncode]]( 'SHA-256', 'Hello world') → '64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c'</code>}}

=== Examples ===

:<code>[[TextLength]]([[TextCharacterEncode]]( ['NFC', 'NFD'], 'á' )) → [1,2]</code>
:<code>[[TextLength]]([[TextCharacterEncode]]( ['NFC', 'NFD'], 'může' )) & rarr; [4,6]</code>
:<code>[[Chr]](0xfb01) → 'ﬁ'</code>
:<code>[[TextLength]]([[TextCharacterEncode]]( ['None', 'NFC','NFD','NFKC','NFKD'], 'ﬁx your résumé' )) → [14,14,16,15,17]</code>

In the last example, note that the first character in «text» is the pre-composed ligature <code>'ﬁ'</code>. The <code>'NFKC'</code> and <code>'NFKD'</code> cases expanded this ligature into two characters.

== See Also ==
* [[ReadTextFile]], [[WriteTextFile]]
* [[TextLocale]]

Encrypting and decrypting

2026-09-22T17:03:53Z

Lchrisman: Created page with "category:Encrypting and hashing functions"

[[category:Encrypting and hashing functions]]

EncryptionKey

2026-09-22T17:03:42Z

Lchrisman: ER 22440

#REDIRECT [[Encrypting and decrypting]]
[[category:Encrypting and hashing functions]]

RandomBytes

2026-09-22T17:01:04Z

Lchrisman: ER 22440

#REDIRECT [[Encrypting and decrypting]]
[[category:Encrypting and hashing functions]]

Encrypt

2026-09-22T17:00:20Z

Lchrisman: ER 22440

#REDIRECT [[Encrypting and decrypting]]
[[category:Encrypting and hashing functions]]

Category:Encrypting and hashing functions

2026-09-22T16:59:47Z

Lchrisman: Created page with "Functions used for encryption, decryption, hashing or other cryptographic purposes."

Functions used for encryption, decryption, hashing or other cryptographic purposes.

Decrypt

2026-09-22T16:59:04Z

Lchrisman: ER 22440

#REDIRECT [[Encrypting and decrypting]]
[[category:Encrypting and hashing functions]]

In-memory binary data terms

2026-09-21T18:01:16Z

Lchrisman: table format fix, | should have been ||

[[category:Expressions]]
[[category:Data Type Functions]]
{{ReleaseBar}}

== Binary data terms (or "blobs") ==

Sometimes it's useful to hold some arbitrary raw, binary data in memory because of its compactness and speed of reading or writing.
The downside is that you can't easily interpret binary data. Such an in-memory block is sometimes called a "blob". The more formal name is a ''binary data term''.

A binary data term is just a block of memory with arbitrary data. Often it's an in-memory copy of a binary file. This can be useful when your code makes many individual reads from different locations in the file, since it avoids repeated file-open and file-close operations, and accesses everything in memory. Sometimes the in-memory image is a portion of a binary file.

== Creating a binary data term in memory ==

The following are ways in which a binary data term can be created.
* A base64 literal, e.g., <code>base64'uC8AMcjLQA=='</code>{{Release|6.4||
* A base16 literal, e.g., <code>base16'b82f0031c8cb40'</code>}}
* <code>[[WriteBinaryFile]]("<>", ...)</code>
* <code>[[ReadBinaryFile]]( filename, typeFlags:7 )</code>
* <code>[[GetFromBinaryData]](..., typeFlags:7)</code>{{Release|6.4||
* <code>[[WriteImageFile]]( "<>", ...)</code>}}
* <code>[[ReadProtoBufFile]]</code> -- ''experimental non-supported function''
Note that functions that read or write to external sources (files) require {{Analytica Developer}} or better.

== Reading the contents of an in-memory binary data term ==
* <code>[[BinaryDataSize]](data)</code> -- returns the number of bytes
* <code>[[GetFromBinaryData]](...)</code>
* <code>[[ParseProtoBuf]]</code> -- experimental, non-supported function

Generally when you are reading a piece of information from the blob, you'll want to interpret the contents in some way. The parameters of [[GetFromBinaryData]] enable you to control this interpretation so that you can read as different non-opaque data types.

{{Release|1=6.6|2=|3=(''New to [[Analytica 6.6]]'') You can also access a single byte (as an integer between 0 and 255) at the 1-based position <code>n</code> using the [[Arrow operator]] syntax:
:<code>x->[n]</code>
or you can extract a subsequence as a new, smaller, [[In-memory binary data terms|binary data term]] using
:<code>x->[m..n]</code>
}}

== Conversions ==

This table summarizes various data transformations to and from binary data formats that you might need.

{| border="1"
! From !! To !! Method !! Required release
|-
| binary file (or part of) || binary data term || [[ReadBinaryFile]] || [[Analytica 6.2]]
|-
| binary data term (or part of) || Binary file || [[WriteBinaryFile]] || [[Analytica 6.2]]
|-
| part of binary data term || another binary data term || <code>[[GetFromBinaryData]](...typeFlags:7)</code> || [[Analytica 6.2]]
|-
| image file || binary data term || <code>[[ReadBinaryFile]](filename,typeFlags:7)</code> || [[Analytica 6.4]]
|-
| in-memory image || binary data term || <code>[[WriteImageFile]]("<>", image)</code> || [[Analytica 6.4]]
|-
| binary data term || image file || <code>[[WriteBinaryFile]](...,typeflags:7) </code><br/>''The binary data must contain the bytes for a valid image.'' || [[Analytica 6.2]]
|-
| binary data term || in-memory image || <code>[[GetFromBinaryData]]( ..., typeFlags:8 )</code> || [[Analytica 6.4]]
|-
| base64 literal || binary data term || [[Base64-encoded_binary_term_literals|<code>base64'....''</code>]] || [[Analytica 6.2]]
|-
| base64 text || binary data term || <code>[[Evaluate]]( f"base64'{txt}'")</code> || [[Analytica 6.2]]
|-
| base64 literal || image || <code>[[GetFromBinaryData]]( base64'...', typeFlags:8 )</code> || [[Analytica 6.4]]
|-
| base64 text || image || <code>[[GetFromBinaryData]]( f"base64'{txt}'", typeFlags:8 )</code> || [[Analytica 6.4]]
|-
| binary data term || base64 literal text || <code>f"{data:b}"</code> || [[Analytica 6.2]]
|-
| hexadecimal literal || binary data term || <code>base16'....''</code> || [[Analytica 6.4]]
|-
| hexadecimal text || binary data term || <code>[[Evaluate]]( f"base16'{txt}'")</code> || [[Analytica 6.4]]
|-
| hexadecimal literal || image || <code>[[GetFromBinaryData]]( base16'...', typeFlags:8 )</code> || [[Analytica 6.4]]
|-
| hexadecimal text || image || <code>[[ImageFromHex]]( text )</code> || [[Analytica 5.0]]
|-
|binary data term || hexadecimal literal text || <code>f"{data:X}"</code> || [[Analytica 6.4]]
|-
| binary data term || hexadecimal text (digits only)|| <code>f"{data:H}"</code> || [[Analytica 6.4]]
|-
|}

== See Also ==
* [[ReadBinaryFile]]
* [[GetFromBinaryData]]
* [[WriteBinaryFile]]
* [[BinaryDataSize]]
* [[Base64-encoded binary term literals]]
* [[ReadImageFile]], [[WriteImageFile]]
* [[Formatted Text Literals]]

Help menu

2026-09-21T15:25:13Z

Lchrisman: EW 22472 - new screenshot for Help menu in 7.2

[[Category:Analytica User Guide]]
[[Category: Menus]]

<breadcrumbs>Analytica User Guide > Menus > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

The [[Help menu]] displays links to Analytica user manuals and contact information for Analytica tech support.

The exact contents of the [[Help menu]] are described in the table below.

:{| class="wikitable"
| rowspan="42" | {{Release?|7.2|[[Image:Help menu 7.2.png]]|[[Image:Help menu 6.0.png]]}}
! style="width: 140px;" | Menu item
! Description
|-
|User guide
|Opens the [[Analytica User Guide]] {{Release|5.0||in your web browser}}.
|-
|Tutorial
|Opens the [[Analytica Tutorial]] {{Release|5.0||in your web browser}}.
|-
|Optimizer guide
|Opens to the [[Analytica Optimizer Guide]] (only appears in Optimizer-enabled version of Analytica).
|-
|{{Release||5.9|Analytica Wiki}}{{Release|6.0||Analytica online docs}}
|Jumps to the [[Analytica Docs]] home page in your web browser, and logs you in automatically if your login credentials are stored. The Docs are the main source for extended Analytica reference materials.
{{Release|5.0||
{{!}}-
{{!}} Functions by category
{{!}} Jumps to an [[:Category:Functions|index of Analytica functions]] on the Docs.
{{!}}-
{{!}}What's new in {{#svarget:anarelease|5.0}}?
{{!}}Jumps to the [[What's new in Analytica {{#svarget:anarelease|5.0}}?]] page.
}}
{{Release|1=|2=7.1|3=
{{!}}-
{{!}}Docs login info...
{{!}}'''''Deprecated:''''' This is no longer used by the docs server. You can log in from on the docs.}}
|-
|Tech support instructions
|Opens your default web browser to the [https://analytica.com/support/technical-support/ Analytica Tech Support page] at https://analytica.com.
|-
|Analytica Q&A forum
|The place to ask Analytica or modeling questions, browse what others have asked or shared, answer questions and share examples.
|-
|Email tech support
|Opens your email system to [mailto:support@lumina.com send an email to Analytica Tech Support].
|-
|Buy/Upgrade Analytica
|Opens to the [https://analytica.com/shoppingcart/productorder Buy Analytica] page on the [https://Analytica.com Analytica.com] web site. You can use this page to find pricing information or to make a purchase or upgrade.
|-
|Contact Lumina...
|Provides contact information for Lumina.
|-
|Update license...
|Displays your current Analytica license information and allows you to update the license code.
|-
|About Analytica...
|Displays useful information such as the application’s edition, release number, your license code, and contact information.
|}

<tip title="Tip">The options that appear on the help menu vary depending on your computer setup and the version
of Analytica you have.</tip>

==See Also==
* [[Menus]]
* [[Help menu and documentation]]
* [[Error message types]]
* [[:Category: Error messages]]

<footer>Window menu / {{PAGENAME}} / Windows and dialogs</footer>

File:Help menu 7.2.png

2026-09-21T15:24:37Z

Lchrisman: updated 7.2 screenshot. Docs login info... has been removed. (EW 22472)

== Summary ==
updated 7.2 screenshot. Docs login info... has been removed. (EW 22472)

Help menu

2026-09-21T15:21:44Z

Lchrisman: EW 22472 - Removal of Docs login info... (Not used server-side any more)

[[Category:Analytica User Guide]]
[[Category: Menus]]

<breadcrumbs>Analytica User Guide > Menus > {{PAGENAME}}</breadcrumbs>
{{ReleaseBar}}

The [[Help menu]] displays links to Analytica user manuals and contact information for Analytica tech support.

The exact contents of the [[Help menu]] are described in the table below.

:{| class="wikitable"
| rowspan="42" | {{Release||4.6|[[Image:Menus_13.png]]}}{{Release|5.0|5.9|[[Image: Help menu 5.0.png]]}}{{Release|6.0||[[Image:Help menu 6.0.png]]}}
! style="width: 140px;" | Menu item
! Description
|-
|User guide
|Opens the [[Analytica User Guide]] {{Release|5.0||in your web browser}}.
|-
|Tutorial
|Opens the [[Analytica Tutorial]] {{Release|5.0||in your web browser}}.
|-
|Optimizer guide
|Opens to the [[Analytica Optimizer Guide]] (only appears in Optimizer-enabled version of Analytica).
|-
|{{Release||5.9|Analytica Wiki}}{{Release|6.0||Analytica online docs}}
|Jumps to the [[Analytica Docs]] home page in your web browser, and logs you in automatically if your login credentials are stored. The Docs are the main source for extended Analytica reference materials.
{{Release|5.0||
{{!}}-
{{!}} Functions by category
{{!}} Jumps to an [[:Category:Functions|index of Analytica functions]] on the Docs.
{{!}}-
{{!}}What's new in {{#svarget:anarelease|5.0}}?
{{!}}Jumps to the [[What's new in Analytica {{#svarget:anarelease|5.0}}?]] page.
}}
{{Release|1=|2=7.1|3=
{{!}}-
{{!}}Docs login info...
{{!}}'''''Deprecated:''''' This is no longer used by the docs server. You can log in from on the docs.}}
|-
|Tech support instructions
|Opens your default web browser to the [https://analytica.com/support/technical-support/ Analytica Tech Support page] at https://analytica.com.
|-
|Analytica Q&A forum
|The place to ask Analytica or modeling questions, browse what others have asked or shared, answer questions and share examples.
|-
|Email tech support
|Opens your email system to [mailto:support@lumina.com send an email to Analytica Tech Support].
|-
|Buy/Upgrade Analytica
|Opens to the [https://analytica.com/shoppingcart/productorder Buy Analytica] page on the [https://Analytica.com Analytica.com] web site. You can use this page to find pricing information or to make a purchase or upgrade.
|-
|Contact Lumina...
|Provides contact information for Lumina.
|-
|Update license...
|Displays your current Analytica license information and allows you to update the license code.
|-
|About Analytica...
|Displays useful information such as the application’s edition, release number, your license code, and contact information.
|}

<tip title="Tip">The options that appear on the help menu vary depending on your computer setup and the version
of Analytica you have.</tip>

==See Also==
* [[Menus]]
* [[Help menu and documentation]]
* [[Error message types]]
* [[:Category: Error messages]]

<footer>Window menu / {{PAGENAME}} / Windows and dialogs</footer>

GoogleAccountEmail

2026-09-18T19:31:31Z

Lchrisman: ER 21588: redirect to the GoogleSheets backend documentation

#REDIRECT [[Functions To Read Excel Worksheets#SpreadsheetOpen]]

[[Category:Integration Functions]]

DisconnectGoogleAccount

2026-09-18T19:31:31Z

Lchrisman: ER 21588: redirect to the GoogleSheets backend documentation

#REDIRECT [[Functions To Read Excel Worksheets#SpreadsheetOpen]]

[[Category:Integration Functions]]

Functions To Read Excel Worksheets

2026-09-18T19:31:30Z

Lchrisman: ER 21588: document GoogleAccountEmail / DisconnectGoogleAccount where readers actually land

[[Category:Excel to Analytica mappings]]
[[Category:Integration Functions]]

__TOC__
{{ReleaseBar}}

These functions let you open an Excel spreadsheet file, and read cells and ranges from it. For writing to a spreadsheet, see [[Functions to Write Data to Excel Worksheets]].

<div id="SpreadsheetOpen" >
== SpreadsheetOpen(filename'', showDialog, title{{Release|7.0||, backend}}{{Release|7.2||, account}}'') ==
</div>

Opens a spreadsheet file and returns a workbook object for use by other functions (such as [[SpreadsheetCell]] or [[SpreadsheetRange]]) to read from or write to the file.

The returned object displays in a result table as <code>«ExcelWorkbook»</code>{{Release|7.2||, <code>«GoogleSheetsWorkbook»</code> }}{{Release|7.0|| or <code>«LibXlWorkbook»</code>, depending on the «backend» used.}} {{Release|1=7.2|2=|3=A workbook opened from a native Google Sheet displays as <code>«GoogleSheetsWorkbook»,</code> but an Excel file stored in Google Drive displays as <code>«LibXlWorkbook»</code>.}}

Unless you include a complete file path in «filename», Analytica looks for the file in the [[CurrentDataFolder]]. You can also provide the name of a workbook that is currently open in Excel, even if it has not yet been saved to disk.

If you omit the optional parameter «showDialog», the file browser dialog opens only if the specified file cannot be found.
* Set «showDialog» to True (<code>1</code>) to force the file browser even if the file exists.
* Set «showDialog» to False (<code>0</code>) to suppress the dialog entirely.

If no file is successfully opened, the function flags an error. You can customize the file dialog caption by passing text to the optional «title» parameter.

[[SpreadsheetOpen]] can return two values: the workbook object and the full path to the file that was opened. This is particularly useful when the user selects a file via the dialog:
::<code>Local (wb, filePath) := SpreadsheetOpen("Data.xlsx");</code>
{{Release|1=7.0|2=|3=
{{Release|1=7.1|2=|3=
=== Creating a new workbook ===
If you pass <code>"New"</code> as the «filename», SpreadsheetOpen creates a new blank workbook with a single empty sheet, without saving to any file. This is useful for building a workbook from scratch before saving it with [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]].

:<code>SpreadsheetOpen("New")</code> — Creates a new workbook using the Excel backend.
:<code>SpreadsheetOpen("New", backend:'LibXl')</code> — Creates a new workbook using the LibXl backend.

You can then add sheets using the <code>+</code> prefix in [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetRange|SpreadsheetSetRange]] or [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetCell|SpreadsheetSetCell]], and save with SpreadsheetSave when done.
}}

=== Backend ===
''(New to [[Analytica 7.0]])''

The optional «backend» parameter determines which underlying engine Analytica uses to handle the spreadsheet.

* <code>'Excel'</code>: (Default) Uses the Microsoft Excel COM interface.
*;Requirements: Requires Microsoft Excel to be installed locally.
*;Capabilities: This backend includes the full Excel calculation engine. If you change cell values using [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]], formulas within the workbook will be recalculated, allowing you to read back computed results. It supports all standard Excel file formats and features.
*;Return type: Returns an «ExcelWorkbook» object.

* <code>'LibXl'</code>: Uses a built-in library for direct file access.
*; Requirements: Does not require Microsoft Excel to be installed.
*; Capabilities: Offers high performance for reading and writing raw data. It is ideal for automated environments (like servers) where Excel might not be present. Note that it does '''''not''''' include a calculation engine; it reads literal values and formulas from the file but cannot "re-calc" a workbook after data is changed.
*; Return type: Returns a «LibXlWorkbook» object.
{{Release|1=7.2|2=|3=

* <code>'GoogleSheets'</code>: Opens a Google Sheets spreadsheet, or an Excel workbook stored in Google Drive, from its link. It is selected automatically when «filename» is a <code>https://docs.google.com/spreadsheets/d/...</code> link (copy it from your browser's address bar while the sheet is open), so «backend» can be omitted.
*; Requirements: A Google account with access to the spreadsheet. The first time, Analytica opens your web browser so you can sign in to Google and select the spreadsheet in Google's file chooser; the connection is remembered on your computer under your Windows account, never in the model, and you can revoke it from your Google account settings. Analytica can open only the spreadsheets you select in that chooser (plus ones it creates itself), so a link to a spreadsheet the chooser did not show cannot be opened. Pass an empty «filename» (or «showDialog»: True) to browse for a spreadsheet.
*; Capabilities: Reads come from a snapshot taken when the workbook is opened. Writes made with [[SpreadsheetSetCell]] and [[SpreadsheetSetRange]], and sheets added or removed, are sent to Google when the computation finishes, when you call [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]](wb), or when the workbook is refreshed: <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code> sends the pending writes and re-downloads the spreadsheet, so the values Google computed (and other people's edits) are seen. A native Google Sheet is exported by Google as an .xlsx snapshot (Google limits the export to 10 MB); an Excel workbook stored in Drive is downloaded as-is and written back as a whole file. The tab names the model sees (<code>SpreadsheetInfo(wb, 'Sheets')</code>, and «sheet» given by name) are the names in the exported snapshot, truncated to 31 characters, while writes are addressed to Google's real tab titles. <code>SpreadsheetOpen("New", backend:'GoogleSheets', title: "My sheet")</code> creates a new Google Sheet in your Drive. The second return value is the spreadsheet's link.
*; Return type: Returns a «GoogleSheetsWorkbook» object for a native Google Sheet, or a «LibXlWorkbook» object for an Excel file stored in Drive. <code>SpreadsheetInfo(wb, 'Backend')</code> returns <code>'GoogleSheets'</code> or <code>'LibXl'</code> accordingly, and <code>SpreadsheetInfo(wb, 'URL')</code> and <code>SpreadsheetInfo(wb, 'Account')</code> give its link and the Google account it was opened with.
*; Advanced: Analytica identifies itself to Google as an application registered by Lumina. An organization that would rather it identified itself as an application of their own -- because their Google Workspace administrator controls which outside applications may reach their data, for example -- can arrange that; see [[Using your own Google OAuth client]], which also covers asking Google for access to every spreadsheet so that the chooser is never shown.
*; Unattended use: A server, a scheduled job or [[Analytica Decision Engine|ADE]] on a machine where nobody is present cannot answer a browser. Give «account» a Google service account instead, and share the spreadsheet with its e-mail address -- see [[Using a Google service account]].
*; Managing the connection: <code>SysLib_Internal::GoogleAccountEmail()</code> answers the Google account Analytica is connected to, or Null when there is none. <code>SysLib_Internal::DisconnectGoogleAccount()</code> revokes that access at Google and forgets the stored connection, returning the address it disconnected; it is a side effect, so evaluate it from a button's OnClick or the [[Typescript Window|Typescript window]] rather than in a Definition. Opening a spreadsheet again then reconnects, and <code>showDialog: True</code> forces the connect dialog if you want to switch accounts. You can also revoke Analytica's access from [https://myaccount.google.com/permissions your Google account's permissions page].
}}
}}
=== Example ===

:<code>SpreadsheetOpen("C:\MyModels\Sales Numbers.xlsx") → ''«ExcelWorkbook»''</code>

<div id="SpreadsheetCell"></div>

=== Getting the file name actually opened ===
Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. [[SpreadsheetOpen]] returns the file path as a second return value, which you can optionally capture using, e.g.,

:<code>[[Local]] (contents, filepath) := [[SpreadsheetOpen]]( ... );</code>

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using [[ComputedBy]] with the default filename as follows:

:Variable TheFilename ::=
::<code>[[ComputedBy]]( TheFileContetns, "defaultFilename.xlsx" ) </code>

:Variable TheWorkbook::=
::<code>( , TheFilename ) := [[SpreadsheetOpen]]( TheFilename )</code>

The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheWorkbook</code> is locally equivalent to:

:<code>[[Local]] (wb, filename ) := [[SpreadsheetOpen]]( TheFilename );</code>
:<code>TheFilename := filename;</code>
:<code>wb</code>

=== Use with Office 2010 ===

If you have installed the "Click-to-Run" version of Office 2010 from a web download, these spreadsheet functions may not work, due to a "feature" introduced in Office 2010 that apparently disables several common operations. In this case, you may need to re-install Office using the MSI-based edition. See how to do this at:

[http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx]

=== Excel 64-bit requires Analytica 64-bit ===

Analytica 32-bit cannot launch Excel 64-bit. (The other way around works). Thus, if you have installed Excel 64-bit (which we recommend), make sure you have installed Analytica 64-bit. If you are a [[Free Edition]] user, you probably have 32-bit installed, but you can install Analytica 64-bit from the [https://www.lumina.com/support/downloads/ Analytica Downloads page].

=== Remembering the selected filename ===

When [[SpreadsheetOpen]]() shows the file dialog and you select a file, it does not save the file name. So, the next time you load the model, you'll have to select the file again. If you want the model to remember the selected file, so it will just load it without asking, prompt using that file name as the default, you can use the '''SpreadsheetOpenEx''' function in the [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]].

=== Having same spreadsheet open in Excel at the same time ===

It is often useful to have the spreadsheet you are working with open in Excel at the same time your model is working with it. When you want to do this, is it best to open it Excel first, before evaluating [[SpreadsheetOpen]], in which case [[SpreadsheetOpen]] connects to the existing Excel process and to the currently open spreadsheet. If you change cells in Excel, then evaluate a spreadsheet read functions, you'll read the new values, and if your model writes to the spreadsheet, you'll see those values reflected immediately in the Excel interface.

When you call [[SpreadsheetOpen]] before opening the model in Excel, the situation is more complex. To understand what happens and how to view the same model in the Excel UI at the same time, see [[Simultaneously opening a spreadsheet in Excel and Analytica]].

=== SpreadsheetOpenFlags ===
A registry setting named <code>SpreadsheetOpenFlags</code> can be set to alter how [[SpreadsheetOpen]] connects to Excel and the initial settings in Excel. There is usually no reason to fiddle with these flags unless you encounter a specific problem. It has been more common to set these flags in server-based applications using ADE than from desktop Analytica.

You'll need to modify the sitting from RegEdit. You can set it in either
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
or
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
For ADE, set it in one of these hives:
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>

Setting it in HKLM causes it to apply from any account on your computer, while setting it from HKCU causes it to apply only to your own account. A setting in HKCU takes precedence over the same setting in HKLM.

Initially the value <code>SpreadsheetOpenFlags</code> will not be present. Create a new 32-bit DWORD with this name. The set the numeric value to an addition of any of these flags that you want:
* 1 = Launch using a COMCreateObject mechanism. (unset)=Launch using a BindToObject method.
*: A BindToObject method (the default for Desktop Analytica) makes it possible to connect to a Workbook running in an active Excel UI. A COMCreateObject mechanism launches a separate instance of Excel every time.
* 2 = Turn off Excel's Interactive flag.
* 4 = Turn off Excel's "Ask to update OLE links" flag.
* 8 = Turn off Excel's "Display Alerts"
* 16 = Disable Excel macros (for security)
* 32 = Close when visible.
*:Normally, if the workbook is currently visible in an Excel UI, Analytica simply disconnects from it, but doesn't force the workbook to close. The Excel UI is then responsible for eventually closing it. This overrides this and forces the workbook to close when the model releases it, even if it is visible.

=== From ADE ===
When using from ADE on a Web Server, we strongly advise against using Excel 2016 on the server. Excel 2010 works fairly well, but Excel 2016 is extremely unstable and has a tendency to fail unpredictably and lock up all other Excel instances. Microsoft responds by saying that Excel 2016 is not supported nor licensed for use on a web server.

When [[SpreadsheetOpen]] is evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the open completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

=== Debugging Errors ===
This section documents failures when '''SpreadsheetOpen''' has been unable to open Excel, and solutions.
* '''''Library not registered''''':
*:If this error occurs when '''SpreadsheetOpen''' is evaluated...
** The article [https://excel.tips.net/T002952_Library_Not_Registered_Error.html Library not registered error] explains how to solve this problem when it is caused by an Excel plug-in. It may be caused by a bad Excel add-in library. You should also run <code>excel.exe /regserver</code>.
** In one case, an Analytica user concluded that an older version of Excel was interfering with his newer 32-bit version of Excel. He uninstalled both and re-installed Excel 64-bit and the problem corrected itself. But, for a different user with this problem, these steps did not correct the problem.
** A common cause of this problem is when stray registry settings from Excel versions that had been installed and uninstalled interfere with your current version of Excel. This is most common after you roll back to an earlier release after uninstalling a later release. To test for this cause, start Power Shell and run:
**::<code>get-childitem -Path "HKLM:\Software\Classes\TypeLib\{00020813-0000-0000-C000-000000000046}"</code>
::If you see more than one version listed, with the most recent version number missing its mapping to Excel, then this is probably the cause. To fix, use <code>RegEdit</code> to delete the hive for the later version number.

== SpreadsheetCell(workbook, sheet, column, row'', what'') ==
</div>

Returns the value (or other information) of a cell of a worksheet given its coordinates. The function fully array abstracts, so you can get a range of cells by specifying the column and/or row as an array.

Parameters:
;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
;«sheet»: The name or number of a worksheet from the workbook. Number 1 is the first worksheet, etc.
:: If you specify <code>sheet: "*"</code>, it returns the cell value from ''column, row'' for all sheets in the workbook, indexed by <code>.Sheet</code>, a local index containing the names of the worksheets. This is a way to get a list of all the worksheets in the workbook. If you specify column and/or rows as arrays, you can also use this to get a 3D array for a range over all worksheets.
;«column»: The column label, e.g., <code>"A", "B"</code>, or <code>"AB"</code>, or the column number as an integer.
;«row»: The row number as an integer
;«what»: optional. Let's you get the formula or format information from the cell. See below under [[SpreadsheetRange]] for details.

If the worksheet cell is empty, it returns [[Null]]. It flags an error if «workbook» is not a valid workbook, if it does not contain «sheet», or if the coordinates are invalid.

=== Examples ===
These expressions are different ways to get the same result, the value from cell ''C7'' in the first sheet, <code>"Sheet1"</code> of workbook:
:<code>SpreadsheetCell(workbook, "Sheet1", "C", 7)</code>
:<code>SpreadsheetCell(workbook, "Sheet1", 3, 7)</code>
:<code>SpreadsheetCell(workbook, 1, 3, 7)</code>

Suppose the spreadsheet contains a 2-D table in the region ''C4:J19''. The columns of this table correspond to the years 2008..2015. The rows correspond to different assets. It is easier to refer to the columns by number, so that the columns "C" thru "J" are columns 3 thru 10. To hold this 2-D table, we need two indexes in Analytica, <code>Time</code> and <code>Asset</code>.

:<code>Index Time := 2008..2015</code>
:<code>Index Asset := 1..16</code>
:<code>Variable Workbook := SpreadsheetOpen("C:\Asset Data.xls")</code>
:<code>Variable Data := SpreadsheetCell( workbook, "Sheet1", @Time+2, @Asset+3)</code>

<div id="SpreadsheetRange">
== SpreadsheetRange(workbook, range'', colIndex, rowIndex, howToIndex, sheet, what'') ==
</div>

Returns the values (or other information) for a range of cells from an Excel worksheet. The «range» can be can be a cell address such as <code>"C7"</code> or cell range <code>"C7:F12"</code>, or the name of a range defined in the spreadsheet. If you want to read or write several cells or ranges in a spreadsheet, it is often convenient to use Excel's name mechanism and refer to them by name in Analytica.

If the range has multiple columns, the result has local index <code>.Column</code> unless you specify «colindex» as a parameter. Similarly, if the range has multiple rows, the result has local index <code>.Row</code> unless you specify «rowindex» as a parameter. Flags in «howToIndex» let you control whether the first row (column) should be used as labels for local index <code>.Row</code> or <code>.Column</code>.

If you specify a sheet name with no cells, e.g. <code>"Inputs!"</code>, it returns a table that includes all cells from that sheet that contain anything.

By default, it returns the number or text values from the range (or <code>NULL</code> if the cell is empty). You can use the «what» parameter to obtain the cell formula, address, format, styles, precedent, and dependent cells for each cell.

=== SpreadsheetRange Parameters ===

SpreadsheetRange has two required parameters:

;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
; «range»: A cell range. It may be a single cell address, e.g. <code>"B10"</code>, a range, e.g. <code>"A1:BC99"</code>, optionally with sheet name, e.g. <code>"Sheet1!A1:BC99"</code>, or a named range, e.g. <code>"Discount_rate"</code> defined in the spreadsheet. If the «range» doesn't mention the sheet name, you must specify «sheet» as a separate parameter.
:: If you specify the range as <code>"Sheet1!"</code>, with nothing after the "!", or omit «range» and specify only «sheet», it returns the smallest rectangular range that includes all used cells within the sheet.

SpreadsheetRange has four optional parameters relating to the indexes for a range with multiple columns or rows, or over multiple sheets:
;«colIndex»: (optional) An index to use for the column dimension of the result.
;«rowIndex»: (optional) An index to use for the row dimension of the result.
;«howToIndex»: (optional) Flags controlling how to index the result when «colIndex» or «rowIndex» are not specified. You can add any of these values to combine their effects:
::<code>1</code>: Force a column index even if the range spans only a single column. Has no effect if you specify «colIndex».
::<code> 2</code>: Force a row index even if the range spans only a single row. Has no effect if you specify «rowIndex».
::<code>4</code>: Use the first row of «range» as column labels in the local index <code>.Column</code>. Exclude this first row in the result returned.
::<code>8</code>: Use the first column of «range» as labels in the local index <code>.Row</code>. Exclude this first column in the result returned..
::<code>16</code>: Suppress the error message that is otherwise given if the sizes of «colIndex» or «rowIndex» do not match the size of the range.
;«sheet»: (optional) The name or number of a worksheet inside the workbook. It can be a list of sheets, in which case, the function will return a 3D table, indexed by this list as the third dimension.
;«what»: (optional) See below for details on this parameter.

=== Indexes of a cell range ===

The result may be a scalar (single cell), a column vector, a row vector, or a 2-D array, depending on the dimensions of the cell range. If the range has more than one row (or column), it will use a local index .Row (.Column) by default. By default, the elements of the .Row index contain the range's row numbers and elements of the column index contain its column labels. For example, if the range is <code>"C7:E12"</code>, <code>.Row</code> would contain the elements <code>[7, 8, 9, 10, 11, 12]</code> and <code>.Column</code> would contain <code>['C', 'D', 'E']</code>.

Or, you can use the first column (row) of the range as the values for the local index .Row (.Column), by specifying <code>howToIndex: 8</code> (<code>howToIndex: 4</code>, or <code>howToIndex: 12</code> for both .Row and .Column.) If you use, the first row (column) of the range as values of the local indexe(es), they will not be included in the value of the array returned. So, in that case, the range must have at least two rows (columns).

Alternatively, if you already have index(es), you can supply them to the «rowIndex» («colIndex») parameters. If you specify a «rowIndex» or «colIndex», that is shorter than the number of rows (columns) in the range, it truncates the result. If an index is too long, it pads the result with [[Null]]. In these cases, it gives a warning message unless you set flag <code>''howToIndex: 16''</code>.

If the range has just one column, the result normally will not have a local .Column index. But, you can force it to use a .Column with one element by setting <code>howToIndex: 1</code>. If you are using a named range and don't know how many columns it has, you might use this option to prevent an error occurring if you use [[Dot_operator::A.I|result.Column]] in an expression. Similarly, you can force it to use local <code>.Row</code> index even when the result has only a single row by specifying <code>howToIndex: 2</code>.

You can obtain the entire range of a worksheet with all cells that contain anything named <code>"Sheet1"</code> by specifying the «range» as <code>"Sheet1!"</code> or by omitting the «range» parameter and specifying just the «sheet» parameter.

=== Examples ===

The following examples use this spreadsheet:

:[[Image:WorksheetRange ExcelShot.jpg]]

This spreadsheet contains these named ranges:
:{| class="wikitable"
! Label !! Range
|-
| Rate || B1
|-
| Year || B3:F3
|-
| Cash_flow || B4:F4
|-
| Divisions || A7:A9
|-
| Employee_count || B7:F9
|}

:<code>SpreadsheetRange(wb, "Rate") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B1") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B3:F3") →</code>
:{| class="wikitable"
! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
| || 2008 || 2009 || 2010 || 2011 || 2012
|}

:<code>Index Year := CopyIndex( SpreadsheetRange(wb, "Year", howToIndex: 1));</code>
:<code>SpreadsheetRange(wb, "Cash_flow", colIndex: Year) →</code>
:{| class="wikitable"
! .Year → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
| || -100 || 10 || 30 || 50 || 60
|}

''Note'': <code>howToIndex: 1</code> was specified for <code>Year</code> here so that we would have a 1-D array even if only one year were present in the spreadsheet.

:<code>SpreadsheetRange(wb, "Employee_count") →</code>
:{| class="wikitable"
! !! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
! rowspan="3" | .Row<br>↓ !! 7
| 24 || 27 || 28 || 32 || 35
|-
! 8
| 13 || 13 || 13 || 13 || 13
|-
! 9
| 25 || 22 || 21 || 19 || 16
|}

:<code>Index Time := [2008, 2009, 2010, 2011, 2012];</code>
:<code>SpreadsheetRange(wb, "A7:F9", colIndex: Time, howToIndex: 8, sheet: 1) →</code>
:{| class="wikitable"
! !! Time → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
! rowspan="3" | .Row<br>↓ !! "Div A"
| 24 || 27 || 28 || 32 || 35
|-
! "Div B"
| 13 || 13 || 13 || 13 || 13
|-
! "Div C"
| 25 || 22 || 21 || 19 || 16
|}

To obtain the list of worksheet names:
:<code>SpreadsheetCell(wb, "*", 1, 1).Sheet</code>

To obtain all used cells in sheet named "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2")</code>

To obtain the number format of all cells in "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2", what:"NumberFormat")</code>

=== SpreadsheetRange «what» parameter ===

By default, SpreadsheetRange() returns the value of the cell(s) in the range, but you can use the «what» parameter to obtain the formula, cell style and formats, cell address, predecessor or dependent cells of each cell:
;«what»: (optional). By default, SpreadsheetRange returns the value of the range, but you can use this parameter to obtain its formula, or cell style parameters. Possible values:
::<code>"Value"</code>: (Default) The computed value. Excel dates become Analytica date-time numbers, which display as dates.
::<code>"NumericValue"</code>: The computed value, but dates are returned as numbers.
::<code>"Formula"</code>: The cell formula as a text value in the normal Excel format starting with "=", e.g., <code>"=Sum(D4:D10)"</code>
::<code>"RelativeFormula"</code>: The cell formula using relative offset format, e.g., <code>"=Sum(RC[-9]:R[+6]C[-9])"</code>

==== «what» parameter cell formats ====
::<code>"NumberFormat"</code>: The cell number format as text.
::<code>"BackColor"</code>: Cell background color as integer: ''red*65536 + green*256 + blue''
::<code>"Text Color"</code>: Font color as an integer: ''red*65536 + green*256 + blue''
::<code>"FontName"</code>: Name of the font used to display the cell
::<code>"FontSize"</code>: Point size of the font displayed in the cell
::<code>"FontStyle"</code>: Special font styles for cell separated by spaces, may include "bold italic underline strikethrough subscript superscript outline shadow"
::<code>"HorizontalAlignment"</code>: Text justification, one of: <code>'Left', 'Center', 'Right', 'Justify', 'Distributed', 'Fill'</code>. (''new to [[Analytica 5.0]]'')
::<code>"VerticalAlignment"</code>: Text vertical justification, one of: <code>'Top', 'Middle', 'Bottom', 'Justify', 'Distributed'</code>. (''new to [[Analytica 5.0]]'')
::<code>"WrapText"</code>: <code>0</code> or <code>1</code> controls whether text is word wrapped to fit in the cell.
::<code>"Border(Left|Right|Up|Down)"</code> show a border to left, right, above, or below the cell.
::<code>"Border(Left|Right|Up|Down)Color"</code>: Return the color of the specified side of the border as an RGB number -- E.g., <code>"BorderLeftColor"</code> returns an integer equal to ''red*65535+green*256+blue''
::<code>"Border (Left|Right|Up|Down) Style"</code>: Style of indicated border, or [[Null]] if not set. May be <code>"Solid", "Dash", "DashDot", "DashDotDot", "Dot", "Double"</code>, or <code>"SlantDashDot"</code>.
::<code>"Border (Left|Right|Up|Down) Weight"</code>: Thickness of indicated border, usually between 1 and 4

==== «what» parameter cell addresses ====
::<code>"Address"</code>: The address of the cell range, e.g., <code>"B12:C13"</code>
::<code>"AddressR1C1"</code>: The address of the cell range in R1C1 format, e.g., <code>"R12C2:R13C3"</code>
::<code>"Sheet"</code>: The sheet name where the cell range exists.
::<code>"RangeName"</code>: The name of the range, if it is a named range.

==== «what» parameter cell precedents and dependents ====

::<code>"DirectPrecedents"</code>: Addresses of all cells mentioned in the cell formula, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not precedents in other sheets.
::<code>"DirectPrecedentsRelative"</code>: Same as "DirectPrecedents", but cells are given by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"DirectDependents"</code>: Addresses of all cells whose formula mentions this cell, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not dependents in other sheets.
::<code>"DirectDependentsRelative"</code>: Same as <code>"DirectDependents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Precedents"</code>: Addresses of all cells in the current worksheet mentioned in the formula of this cell and the formulas of its direct precedents. It does not include cells reached by paths passing through other sheets.
::<code>"PrecedentsRelative"</code>: Same as <code>"Precedents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Descendants"</code>: Description of all cells in the current worksheet that depend directly or indirectly on the given cell. It does not include cells reached by paths passing through other sheets.
::<code>"DirectDescendantsRelative"</code>: Same as <code>"DirectDescendants"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.

=== Errors in SpreadsheetRange parameters ===
In a call to SpreadsheetRange(wb, range):
* If range refers to a sheet, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the worksheet 'sheet' was not found."
* If range refers to a named range, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the indicated named cell range, 'x', was not found."
* If range refers to a cell address with bad syntax, e.g. "ted!A1:R3C6", it gives an error message saying "the range named A1:R3C6 was not found in Excel worksheet 'ted'."

<div id="SpreadsheetInfo">
== SpreadsheetInfo(workbook, item) ==
</div>

SpreadsheetInfo gets various kinds of information about the spreadsheet («workbook») specified by parameter «item»:

{| class="wikitable"
! item !! Description
|-
| <code>"AcceptLabelsInFormulas"</code> || True when you can use labels in worksheet formulas. This is usually false.
|-
| <code>"Account"</code> || ''([[Analytica 7.2|7.2]])'' The Google account a workbook opened from Google Sheets or Google Drive is connected with. Null for other workbooks.
|-
| <code>"ActiveSheet"</code> || The number of the active (displayed) worksheet.
|-
| <code>"Author"</code> || The name of the author, usually the name of the person who created the spreadsheet as recorded by Windows OS.
|-
| <code>"Backend"</code> || ''([[Analytica 7.2|7.2]])'' Which engine holds the workbook: <code>'Excel'</code>, <code>'LibXl'</code> or <code>'GoogleSheets'</code> (see the «backend» parameter of [[SpreadsheetOpen]]).
|-
| <code>"CalculationMode"</code> || The calculation mode set for the workbook, which may be "Automatic", "Manual" or "Semiautomatic", meaning automatic except for data tables.
|-
| <code>"CalculationState"</code> || ''([[Analytica 5.0|5.0]])'' The current state of Excel's calculation engine, either <code>"Calculating"</code>, <code>"Pending"</code> or <code>"Done"</code>.
|-
| <code>"CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of the Excel calculation engine that the current workbook was last calculated in. If it was saved in an earlier version of Excel and hasn't yet been fully calculated, the value is 0. You can compare this to the "Excel.CalculationVersion" to determine whether it was last re-calculated using the same calculation engine as your current installed Excel.
|-
| <code>"CodeName"</code> ||
|-
| <code>"Date1904"</code> || The base for dates used in the workbook.
|-
| <code>"DecimalSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character used to separate a whole number from its fractional part. In English-speaking countries this is '.' (a dot).
|-
| <code>"Excel.CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of calculation engine for your installed version of Excel.
|-
| <code>"Filename"</code> || The name of the file, including the full file path.
|-
| <code>"Name"</code> || The name of the file, without the file path.
|-
| <code>"Names"</code> || A list of all the named ranges.
|-
| <code>"OperatingSystem"</code> || ''([[Analytica 5.0|5.0]])'' The name of the operating system that your Excel instance is running on, as reported by Excel.
|-
| <code>"ReadOnly"</code> || True (1) if the file is saved as Readonly.
|-
| <code>"Saved"</code> || False (0) if it has unsaved changes.
|-
| <code>"SelectedRange"</code> || The currently selected Range.
|-
| <code>"SelectedRangeR1C1"</code> || The currently selected Range specified by row and column number.
|-
| <code>"Sheets"</code> || A list of the names of all the worksheets
|-
| <code>"ThousandsSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character Excel uses to group thousands when displaying a large number. In English-speaking countries this is ',' (a comma). For example, in the number <code>1,234,456.78</code>, groups of thousands are separated by commas.
|-
| <code>"Title"</code> || The title of the spreadsheet
|-
| <code>"URL"</code> || ''([[Analytica 7.2|7.2]])'' The link of a workbook opened from Google Sheets or Google Drive. Null for other workbooks.
|-
| <code>"UseSystemSeparators"</code> || ''([[Analytica 5.0|5.0]])'' True when Excel uses <code>"DecimalSeparator"</code> and <code>"ThousandsSeparator"</code> for displaying numbers.
|-
| <code>"Version"</code> || ''([[Analytica 5.0|5.0]])'' The version number (text) for the installed release of Excel. Excel 2010 is "14.0", Excel 2013 is "15.0" and Excel 2016 is "16.0".
|-
| <code>"Visible"</code> || True when the Excel UI is visible.
|} The items above marked with ''([[Analytica 5.0|5.0]])'' require [[Analytica 5.0]] or better; those marked ''([[Analytica 7.2|7.2]])'' require [[Analytica 7.2]].

== History==

Functions for reading cells from Excel were first present in Analytica 4.1 with functions named [[OpenExcelFile]], [[WorksheetCell]] and [[WorksheetRange]], although these were labelled as ''experimental'', and the present functions were not officially available until 4.2.0. The old names are now deprecated, replaced with [[SpreadsheetOpen]], [[SpreadsheetCell]] and [[SpreadsheetRange]]. The old functions still work, but may be removed in future Analytica releases. The parameters have changed slightly from [[WorksheetRange]] to [[SpreadsheetRange]], with the sheet parameter moved from being the second to being the last parameter and now optional -- no longer required for named ranges or ranges of the form <code>"Sheet1!A1:Z99"</code>.

[[SpreadsheetInfo]] was introduced in [[Analytica 4.5]]. These options to [[SpreadsheetInfo]] were added in [[Analytica 5.0]]: "Version", "CalculationVersion", "Excel.CalculationVersion", "UseSystemSeparators", "DecimalSeparator", "ThousandsSeparator", and "CalculationState".

The color options for «what» incorrectly returned numbers in 0x00bbggrr order, instead of 0x00rrggbb order prior to [[Analytica 5.0]]. (This was a bug -- the documentation stated it should be 0x00rrggbb). Various options to the «what» parameter of [[SpreadsheetCell]] and [[SpreadsheetRange]] have appeared at different releases. The options <code>'HorizontalAlignment'</code> and <code>'VerticalAlignment'</code> appeared in [[Analytica 5.0]]. Options <code>'Address'</code>, <code>'AddressR1C1'</code>, <code>'Sheet'</code> and <code>'RangeName'</code> appeared in [[Analytica 4.6]]. The remaining options appeared in [[Analytica 4.4]], except for <code>'Value'</code>, <code>'NumericValue'</code>, <code>'Formula'</code>' and <code>'RelativeFormula'</code>, which appeared when the «what» parameter was introduced in [[Analytica 4.3]].

{{Release|1=7.2|2=|3=The <code>'GoogleSheets'</code> «backend» of [[SpreadsheetOpen]] (Google Sheets spreadsheets and Excel workbooks stored in Google Drive, opened from their link), and the "Backend", "URL" and "Account" items of [[SpreadsheetInfo]], were added in [[Analytica 7.2]].}}

== See Also ==

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[media:Spreadsheet Helper lib.ana|Spreadsheet Helper lib.ana]]
* [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]]
* [[Media:Functions for Reading Excel Worksheets.ana|Reading Excel Worksheets.ana]]
* [[Read and Write Spreadsheets]]
* [[Excel spreadsheets read and write]]
* [[Functions to Write Data to Excel Worksheets]] -- [[SpreadsheetSetCell]], [[SpreadsheetSetRange]] and [[SpreadsheetSave]]
* {{Release|1=7.2|2=|3=[[Using your own Google OAuth client]] -- connecting to Google Sheets through your own Google Cloud registration}}
* {{Release|1=7.2|2=|3=[[Using a Google service account]] -- opening a Google Sheet with no browser and nobody present}}
* You can also use [[DbQuery| ODBC]] -- a standard database access method to read from Excel spreadsheets.
* [[SuppressExcelAlerts]]
* [[Excel to Analytica Translation]]
* [[Excel to Analytica Mappings]]
* [[ReadTextFile]]
* [[ReadCsvFile]]
* You can use these functions from [[Excel Functions from ADE| ADE]].
* These spreadsheet functions above are more flexible than [[OLE linking]] which is also available.
* [[OLE linking]] </div>

Category:Analytica MCP Platform

2026-09-18T18:07:15Z

Lchrisman: Created page with "The Analytica MCP Platform (AMP) is a Lumina product offering that runs Analytica models headlessly while exposing a Model Context Protocol (MCP) API. It is designed especially for use cases involving a front-end language model interface. This category page lists pages specifically related to AMP."

The Analytica MCP Platform (AMP) is a Lumina product offering that runs Analytica models headlessly while exposing a Model Context Protocol (MCP) API. It is designed especially for use cases involving a front-end language model interface.

This category page lists pages specifically related to AMP.

Using a Google service account

2026-09-18T18:01:37Z

Lchrisman: categories ADE & AMP

[[Category:Integration Functions]]
[[Category:Analytica Decision Engine]]
[[Category:Analytica MCP Platform]]

{{ReleaseBar}}

''New to [[Analytica 7.2]]''

{{Release|1=7.2|2=|3=
Normally the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]] opens a spreadsheet as ''you'': the first time, your web browser opens, you sign in to Google and choose the spreadsheet, and the connection is remembered on your computer.

That cannot work where there is nobody at a browser -- a server, a scheduled task, a build, a model running under [[Analytica Decision Engine|ADE]] on a machine nobody signs in to. For those, Analytica can open a spreadsheet as a Google '''service account''': an account that belongs to a program rather than a person, and that proves who it is with a key file instead of a sign-in. You share the spreadsheet with the service account's e-mail address, exactly as you would share it with a colleague, and pass its key to [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] in the «account» parameter.

== When to use one ==

* An unattended machine: a scheduled model run, a server, a continuous-integration job, or ADE on a machine where nobody has ever run the desktop connect flow.
* A spreadsheet that should be read as ''itself'' rather than as whoever happens to run the model -- a reference dataset the model's author maintains, where you do not want every reader to need their own access to it.

Do '''not''' use one for an ordinary desktop model. There the browser connection is simpler, it keeps each person reading with their own permissions, and it needs no key to look after.

== Creating the service account ==

# In the [https://console.cloud.google.com/ Google Cloud console], choose or create a project, and enable the '''Google Drive API''' and the '''Google Sheets API''' for it. (The Picker API is not needed -- a service account never sees a file chooser.)
# Go to IAM and admin, '''Service accounts''', and create one. Give it a name you will recognize later. It needs no project roles: the only access that matters is the sharing you do in step 4.
# Open the new account, go to '''Keys''', '''Add key''', '''Create new key''', type '''JSON'''. Google downloads a small .json file, once -- it cannot be downloaded again. This file is the account's password; treat it like one.
# Copy the account's e-mail address, which looks like <code>something@''your-project''.iam.gserviceaccount.com</code>, and '''share each spreadsheet with it''' in Google Sheets exactly as you would with a person: Share, paste the address, Viewer for read-only or Editor if the model writes. A service account sees nothing that has not been shared with it.

The service account needs no consent screen, no Google verification, and no security assessment, because nobody is being asked to grant it anything: it holds its own credentials, and you decide what it can reach by sharing.

== Giving Analytica the key ==

Put the contents of the .json file in a [[Secret]], and pass the Secret as the «account» parameter:

:<code>SpreadsheetOpen("https://docs.google.com/spreadsheets/d/''id''/edit", account: Sheets_Robot_Key)</code>

where <code>Sheets_Robot_Key</code> is a Secret whose value is the whole JSON text. Set its '''Sinks''' to <code>SpreadsheetOpen</code> and its '''Destination''' to <code>https://oauth2.googleapis.com/</code>, so the key can be used for this and nothing else; Analytica refuses the substitution otherwise. Which storage kind the Secret uses -- in the model, an environment variable, per machine user, or a vault -- is your choice, and is the thing that decides who else can run the model.

Passing the JSON as a plain text literal works too, and is the wrong thing to do in a saved model: anyone who opens the file then has the key.

The «backend» parameter is not needed; a Google Sheets link selects the backend by itself.

== What is different with a service account ==

* '''Nothing interactive ever happens.''' No browser opens, no dialog appears, and nothing waits for a person. If the account cannot reach the spreadsheet the call reports that and stops.
* '''The file chooser is not involved.''' Any spreadsheet shared with the account opens directly from its link. There is no "pick one" mode, so <code>SpreadsheetOpen("")</code> and <code>showDialog: True</code> have nothing to offer.
* '''It ignores the desktop's connection entirely.''' The Windows user's own Google connection, and the [[Using your own Google OAuth client|client-registration settings]], play no part; the key carries its own identity and its own permissions. You can use a service account for one spreadsheet and your own connection for another in the same model.
* '''Reads and writes behave exactly as they do otherwise''': a snapshot on open, writes sent when the computation finishes, on <code>SpreadsheetSave(wb)</code>, or on <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code>. Give the account '''Editor''' on the spreadsheet if the model writes to it.
* <code>SpreadsheetInfo(wb, 'Account')</code> reports the service account's address, so a model can say which identity a workbook was opened with.
* <code>SpreadsheetOpen("New", backend:'GoogleSheets', account: ''key'')</code> does work, but the new spreadsheet is created in the '''service account's own Drive''', where no person can see it. That is occasionally what you want for scratch space and almost never what you want otherwise; a service account has no Drive anyone can browse.

== When it does not work ==

The most common failure is the one that has nothing to do with Analytica: the spreadsheet was never shared with the service account. Analytica says so by name --

:''The Google service account ''name''@''project''.iam.gserviceaccount.com cannot open the spreadsheet ...''

-- and the cure is to share it at that address. Note that sharing a ''folder'' with the account shares what is in it, which is usually the tidier arrangement for a model that reads several spreadsheets.

A key that is damaged, truncated, or not a service-account key at all is reported when the call is evaluated, before any network request, so a mistyped Secret fails immediately rather than halfway through a run.

Some organizations' Workspace policies block service-account keys from being created at all, or disable them after a period. If the console will not produce a key, that is an administrator's setting, not a Google-wide limit.

=== Not supported ===

Domain-wide delegation -- a service account impersonating a member of your Workspace -- is not supported. The service account acts as itself, and sees what has been shared with it.
}}

== See Also ==

* [[Functions To Read Excel Worksheets]] -- [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] and the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]]
* [[Using your own Google OAuth client]]
* [[Secret]]
* [[Analytica Decision Engine]]

Using a Google service account

2026-09-18T17:59:53Z

Lchrisman:

[[Category:Integration Functions]]
{{ReleaseBar}}

''New to [[Analytica 7.2]]''

{{Release|1=7.2|2=|3=
Normally the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]] opens a spreadsheet as ''you'': the first time, your web browser opens, you sign in to Google and choose the spreadsheet, and the connection is remembered on your computer.

That cannot work where there is nobody at a browser -- a server, a scheduled task, a build, a model running under [[Analytica Decision Engine|ADE]] on a machine nobody signs in to. For those, Analytica can open a spreadsheet as a Google '''service account''': an account that belongs to a program rather than a person, and that proves who it is with a key file instead of a sign-in. You share the spreadsheet with the service account's e-mail address, exactly as you would share it with a colleague, and pass its key to [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] in the «account» parameter.

== When to use one ==

* An unattended machine: a scheduled model run, a server, a continuous-integration job, or ADE on a machine where nobody has ever run the desktop connect flow.
* A spreadsheet that should be read as ''itself'' rather than as whoever happens to run the model -- a reference dataset the model's author maintains, where you do not want every reader to need their own access to it.

Do '''not''' use one for an ordinary desktop model. There the browser connection is simpler, it keeps each person reading with their own permissions, and it needs no key to look after.

== Creating the service account ==

# In the [https://console.cloud.google.com/ Google Cloud console], choose or create a project, and enable the '''Google Drive API''' and the '''Google Sheets API''' for it. (The Picker API is not needed -- a service account never sees a file chooser.)
# Go to IAM and admin, '''Service accounts''', and create one. Give it a name you will recognize later. It needs no project roles: the only access that matters is the sharing you do in step 4.
# Open the new account, go to '''Keys''', '''Add key''', '''Create new key''', type '''JSON'''. Google downloads a small .json file, once -- it cannot be downloaded again. This file is the account's password; treat it like one.
# Copy the account's e-mail address, which looks like <code>something@''your-project''.iam.gserviceaccount.com</code>, and '''share each spreadsheet with it''' in Google Sheets exactly as you would with a person: Share, paste the address, Viewer for read-only or Editor if the model writes. A service account sees nothing that has not been shared with it.

The service account needs no consent screen, no Google verification, and no security assessment, because nobody is being asked to grant it anything: it holds its own credentials, and you decide what it can reach by sharing.

== Giving Analytica the key ==

Put the contents of the .json file in a [[Secret]], and pass the Secret as the «account» parameter:

:<code>SpreadsheetOpen("https://docs.google.com/spreadsheets/d/''id''/edit", account: Sheets_Robot_Key)</code>

where <code>Sheets_Robot_Key</code> is a Secret whose value is the whole JSON text. Set its '''Sinks''' to <code>SpreadsheetOpen</code> and its '''Destination''' to <code>https://oauth2.googleapis.com/</code>, so the key can be used for this and nothing else; Analytica refuses the substitution otherwise. Which storage kind the Secret uses -- in the model, an environment variable, per machine user, or a vault -- is your choice, and is the thing that decides who else can run the model.

Passing the JSON as a plain text literal works too, and is the wrong thing to do in a saved model: anyone who opens the file then has the key.

The «backend» parameter is not needed; a Google Sheets link selects the backend by itself.

== What is different with a service account ==

* '''Nothing interactive ever happens.''' No browser opens, no dialog appears, and nothing waits for a person. If the account cannot reach the spreadsheet the call reports that and stops.
* '''The file chooser is not involved.''' Any spreadsheet shared with the account opens directly from its link. There is no "pick one" mode, so <code>SpreadsheetOpen("")</code> and <code>showDialog: True</code> have nothing to offer.
* '''It ignores the desktop's connection entirely.''' The Windows user's own Google connection, and the [[Using your own Google OAuth client|client-registration settings]], play no part; the key carries its own identity and its own permissions. You can use a service account for one spreadsheet and your own connection for another in the same model.
* '''Reads and writes behave exactly as they do otherwise''': a snapshot on open, writes sent when the computation finishes, on <code>SpreadsheetSave(wb)</code>, or on <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code>. Give the account '''Editor''' on the spreadsheet if the model writes to it.
* <code>SpreadsheetInfo(wb, 'Account')</code> reports the service account's address, so a model can say which identity a workbook was opened with.
* <code>SpreadsheetOpen("New", backend:'GoogleSheets', account: ''key'')</code> does work, but the new spreadsheet is created in the '''service account's own Drive''', where no person can see it. That is occasionally what you want for scratch space and almost never what you want otherwise; a service account has no Drive anyone can browse.

== When it does not work ==

The most common failure is the one that has nothing to do with Analytica: the spreadsheet was never shared with the service account. Analytica says so by name --

:''The Google service account ''name''@''project''.iam.gserviceaccount.com cannot open the spreadsheet ...''

-- and the cure is to share it at that address. Note that sharing a ''folder'' with the account shares what is in it, which is usually the tidier arrangement for a model that reads several spreadsheets.

A key that is damaged, truncated, or not a service-account key at all is reported when the call is evaluated, before any network request, so a mistyped Secret fails immediately rather than halfway through a run.

Some organizations' Workspace policies block service-account keys from being created at all, or disable them after a period. If the console will not produce a key, that is an administrator's setting, not a Google-wide limit.

=== Not supported ===

Domain-wide delegation -- a service account impersonating a member of your Workspace -- is not supported. The service account acts as itself, and sees what has been shared with it.
}}

== See Also ==

* [[Functions To Read Excel Worksheets]] -- [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] and the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]]
* [[Using your own Google OAuth client]]
* [[Secret]]
* [[Analytica Decision Engine]]

Using your own Google OAuth client

2026-09-18T16:24:46Z

Lchrisman:

[[Category:Integration Functions]]
{{ReleaseBar}}

''Requires [[Analytica 7.2]]''

{{Release|1=7.2|2=|3=
When the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]] of [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] connects to Google, Analytica identifies itself to Google as an application named '''Analytica''', registered by Lumina Decision Systems. That needs no setup and is the right arrangement for nearly everyone.

This page is for the few organizations that would rather have Analytica identify itself as an application registered by '''them'''. It describes what that does and does not change, when it is worth the trouble, and how to set it up. If what you need instead is for a server, a scheduled job or [[Analytica Decision Engine|ADE]] to open a spreadsheet with nobody present, see [[Using a Google service account]].

== What the application identity is, and is not ==

The client ID and client secret that Analytica sends to Google say ''which program is asking''. They say nothing about ''who you are'', and nothing about ''which spreadsheets'' it may touch. In particular, using Lumina's registration does '''not''' restrict Analytica to non-confidential spreadsheets:

* Analytica asks Google for one permission, <code>drive.file</code>, which lets it see only the spreadsheets you yourself select in Google's file chooser, plus ones it creates. A confidential spreadsheet is no different from any other: select it in the chooser and Analytica can read and write it.
* No spreadsheet content and no Google credential ever passes through Lumina. Your browser talks to Google, your computer exchanges tokens with Google directly, and the resulting connection is kept in the Windows Credential Manager under your Windows account. Registering your own application changes none of that.
* On its own, your own registration does not remove the browser step, and does not change which spreadsheets the chooser offers you. It is what makes the ''broader permission'' below possible, and that is what removes the chooser.

== Why you might want your own ==

* '''Your organization controls which third-party applications may use its Google Workspace data.''' A Workspace administrator can allow or block individual applications (Admin console, under Security, API controls). If Analytica has not been allowed, connecting fails, or Google's chooser offers nothing you can select. An application registered inside your own organization is under your administrator's control from the start, instead of needing an exception made for an outside one.
* '''You want to skip the file chooser altogether.''' Google will only grant an application permission to ''every'' spreadsheet after a review, and for an outside application that review is an annual paid security assessment. An application registered as '''Internal''' to your own Google Workspace skips it entirely. See [[#Asking for a broader permission]] below.
* '''You want the consent screen, the grants and the audit trail inside your own organization.''' The browser names ''your'' application, the grants appear in your own Google Cloud project, and an administrator can review or revoke them centrally.
* '''You want your own API quota.''' Google counts Drive and Sheets API usage per Cloud project. Your own project gets its own quota, rather than sharing a pool with other Analytica users.
* '''You would rather Analytica's access to your data not depend on an application registered by another company at all.'''

If none of these apply to you, use the built-in registration and ignore this page.

== Registering the application with Google ==

You need a Google Cloud project, which is free.

# In the [https://console.cloud.google.com/ Google Cloud console], create a project, or choose one your organization already uses.
# Enable three APIs for it (APIs and services, then Enable APIs and services): '''Google Drive API''', '''Google Sheets API''' and '''Google Picker API'''. The Picker API is the one that presents the file chooser; without it the connection cannot finish.
# Configure the OAuth consent screen (Google Auth Platform, then Branding). Give it an application name -- this is the name the person sees in the browser, so use one they will recognize -- a user-support e-mail address, and a developer contact address.
#* Choose the '''Internal''' user type if your organization uses Google Workspace and only its own members need to connect. Internal applications skip Google's verification process entirely, which also makes the broader permission below available to you.
#* '''External''' also works for the default permission. Because Analytica asks only for the non-sensitive <code>drive.file</code> permission, an External application can be published without a Google review. While it is left in ''Testing'', though, only the accounts listed as test users can connect, and their connections stop working after seven days.
# Create the credential: APIs and services, Credentials, Create credentials, '''OAuth client ID''', application type '''Desktop app'''. Copy the '''Client ID''' and the '''Client secret''' that Google shows. There is no redirect URI to fill in -- a desktop client may use the local loopback address that Analytica uses.

Google calls the second value a secret, but for a desktop application it is not a true secret: it is distributed inside the program, and Google's own documentation treats installed applications as unable to keep it confidential. Look after it as you would any configuration value, but it is not a password, and on its own it grants access to nothing.

== Telling Analytica to use it ==

Set two values in the registry, under

:<code>HKEY_CURRENT_USER\Software\Lumina Decision Systems</code>

for one Windows user, or under

:<code>HKEY_LOCAL_MACHINE\SOFTWARE\Lumina Decision Systems</code>

for everyone on the computer. If a value appears in both, the HKEY_CURRENT_USER one wins.

;<code>GoogleOAuthClientId</code> (REG_SZ)
:The full client ID, ending in <code>.apps.googleusercontent.com</code>
;<code>GoogleOAuthClientSecret</code> (REG_SZ)
:The client secret
;<code>GoogleOAuthScope</code> (REG_SZ)
:''Optional.'' See [[#Asking for a broader permission]] below. Leave it unset to keep the default.

That key is deliberately the one '''above''' the per-product keys, so a single setting covers Analytica, ADE and the other Analytica products alike. Use it: one Google connection is shared by every product running as the same Windows user, and it is remembered under the client ID, so a client ID set for only one of them would leave the others unable to find the connection. (A value under a product's own key -- <code>...\Lumina Decision Systems\Analytica</code>, <code>...\ADEW</code> -- still wins for that product, if you ever need to make one of them differ.) None of these keys has a release number in it, so the setting applies to every installed release.

Set both the ID and the secret. If the ID is given without the secret, Google refuses the connection. As a .reg file:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Lumina Decision Systems]
"GoogleOAuthClientId"="123456789012-examplexample.apps.googleusercontent.com"
"GoogleOAuthClientSecret"="GOCSPX-exampleexampleexample"

Removing the values restores the built-in registration.

The change takes effect at the next connection; there is no need to restart Analytica. Connections are remembered separately for each client ID, so the first spreadsheet you open after the change asks you to connect once more. Your earlier connection is left untouched, and is used again if you remove the values.

== Asking for a broader permission ==

By default Analytica asks Google for one permission, <code>https://www.googleapis.com/auth/drive.file</code>, which covers only the spreadsheets you pick in Google's chooser. That is why a spreadsheet you have not used with Analytica before sends you to the browser once.

The optional <code>GoogleOAuthScope</code> value replaces that request. Setting it to

:<code>https://www.googleapis.com/auth/drive</code>

asks instead for access to your Drive as a whole. The effect on everyday use is that '''the file chooser disappears''': you connect once, and after that every spreadsheet link you paste simply opens, in any model, with no further browser trips. The trade is the single consent screen at the start, which now asks for a great deal more, so it is a decision to take deliberately rather than a convenience to switch on by reflex.

Two things to know before you use it:

* '''In practice this needs an Internal application.''' Google classes whole-Drive access as a ''restricted'' scope: an External application must pass an annual, paid third-party security assessment before Google will allow it, which is why Analytica's built-in registration does not offer this. An '''Internal''' application in your own Workspace is exempt from verification, so the setting works immediately there. Do not set it while using Lumina's built-in registration.
* '''<code>.../auth/spreadsheets</code> alone is not enough.''' Analytica reads a native Google Sheet through Drive's export, and an Excel workbook stored in Drive through a Drive download, so it needs a Drive permission and not only a Sheets one. Give the value <code>https://www.googleapis.com/auth/drive</code>, or a space-separated list containing it.

Changing this value makes Analytica ask you to connect again, because the connection it has was granted under the old permission. With any value that does not include <code>drive.file</code> there is no chooser to browse in, so <code>SpreadsheetOpen("")</code> and <code>showDialog: True</code> no longer offer one -- give a spreadsheet link instead.

== Checking that it worked, and disconnecting ==

Open any Google Sheets link with [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]]. The browser page that asks for permission should now name ''your'' application rather than Analytica. Afterwards:

:<code>SysLib_Internal::GoogleAccountEmail()</code> -- the Google account now connected, or Null when there is none.
:<code>SpreadsheetInfo(wb, 'Account')</code> -- the account an open workbook was opened with.

To disconnect -- which revokes the access at Google and forgets the stored connection -- evaluate

:<code>SysLib_Internal::DisconnectGoogleAccount()</code>

from a button's OnClick, or in the [[Typescript Window|Typescript window]]. It is a side effect, so it is refused inside a variable's Definition. It returns the e-mail address of the account that was disconnected, or Null when none was connected. You can also revoke Analytica's access at any time from [https://myaccount.google.com/permissions your Google account's permissions page].

== Notes and limits ==

* One Google connection is remembered at a time for a given client ID, for the Windows user who made it. [[Analytica Decision Engine|ADE]] scripts running as the same Windows user share that connection, which is why connecting once in Analytica is enough for them -- and why the settings above belong in the shared registry key.
* A model published to the [[Analytica Cloud Platform]] does not use these settings. There, each person connects their own Google account through the ACP server's own registration, and the settings on the author's computer play no part.
* These settings say how the person at the browser connects. They have no effect on [[Using a Google service account|a service account]] given to <code>SpreadsheetOpen</code>'s «account» parameter, which carries its own credentials and its own permissions.
}}

== See Also ==

* [[Functions To Read Excel Worksheets]] -- [[Functions To Read Excel Worksheets#SpreadsheetOpen|SpreadsheetOpen]] and the [[Functions To Read Excel Worksheets#Backend|GoogleSheets backend]]
* [[Using a Google service account]]
* [[Functions to Write Data to Excel Worksheets]]
* [[SpreadsheetInfo]]
* [[Analytica Cloud Platform]]

Functions To Read Excel Worksheets

2026-09-18T15:47:06Z

Lchrisman: ER 21588 Phase 4: link the service-account page (re-applying; a cached action=raw fetch reverted it)

[[Category:Excel to Analytica mappings]]
[[Category:Integration Functions]]

__TOC__
{{ReleaseBar}}

These functions let you open an Excel spreadsheet file, and read cells and ranges from it. For writing to a spreadsheet, see [[Functions to Write Data to Excel Worksheets]].

<div id="SpreadsheetOpen" >
== SpreadsheetOpen(filename'', showDialog, title{{Release|7.0||, backend}}{{Release|7.2||, account}}'') ==
</div>

Opens a spreadsheet file and returns a workbook object for use by other functions (such as [[SpreadsheetCell]] or [[SpreadsheetRange]]) to read from or write to the file.

The returned object displays in a result table as <code>«ExcelWorkbook»</code>{{Release|7.2||, <code>«GoogleSheetsWorkbook»</code> }}{{Release|7.0|| or <code>«LibXlWorkbook»</code>, depending on the «backend» used.}} {{Release|1=7.2|2=|3=A workbook opened from a native Google Sheet displays as <code>«GoogleSheetsWorkbook»,</code> but an Excel file stored in Google Drive displays as <code>«LibXlWorkbook»</code>.}}

Unless you include a complete file path in «filename», Analytica looks for the file in the [[CurrentDataFolder]]. You can also provide the name of a workbook that is currently open in Excel, even if it has not yet been saved to disk.

If you omit the optional parameter «showDialog», the file browser dialog opens only if the specified file cannot be found.
* Set «showDialog» to True (<code>1</code>) to force the file browser even if the file exists.
* Set «showDialog» to False (<code>0</code>) to suppress the dialog entirely.

If no file is successfully opened, the function flags an error. You can customize the file dialog caption by passing text to the optional «title» parameter.

[[SpreadsheetOpen]] can return two values: the workbook object and the full path to the file that was opened. This is particularly useful when the user selects a file via the dialog:
::<code>Local (wb, filePath) := SpreadsheetOpen("Data.xlsx");</code>
{{Release|1=7.0|2=|3=
{{Release|1=7.1|2=|3=
=== Creating a new workbook ===
If you pass <code>"New"</code> as the «filename», SpreadsheetOpen creates a new blank workbook with a single empty sheet, without saving to any file. This is useful for building a workbook from scratch before saving it with [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]].

:<code>SpreadsheetOpen("New")</code> — Creates a new workbook using the Excel backend.
:<code>SpreadsheetOpen("New", backend:'LibXl')</code> — Creates a new workbook using the LibXl backend.

You can then add sheets using the <code>+</code> prefix in [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetRange|SpreadsheetSetRange]] or [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetCell|SpreadsheetSetCell]], and save with SpreadsheetSave when done.
}}

=== Backend ===
''(New to [[Analytica 7.0]])''

The optional «backend» parameter determines which underlying engine Analytica uses to handle the spreadsheet.

* <code>'Excel'</code>: (Default) Uses the Microsoft Excel COM interface.
*;Requirements: Requires Microsoft Excel to be installed locally.
*;Capabilities: This backend includes the full Excel calculation engine. If you change cell values using [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]], formulas within the workbook will be recalculated, allowing you to read back computed results. It supports all standard Excel file formats and features.
*;Return type: Returns an «ExcelWorkbook» object.

* <code>'LibXl'</code>: Uses a built-in library for direct file access.
*; Requirements: Does not require Microsoft Excel to be installed.
*; Capabilities: Offers high performance for reading and writing raw data. It is ideal for automated environments (like servers) where Excel might not be present. Note that it does '''''not''''' include a calculation engine; it reads literal values and formulas from the file but cannot "re-calc" a workbook after data is changed.
*; Return type: Returns a «LibXlWorkbook» object.
{{Release|1=7.2|2=|3=

* <code>'GoogleSheets'</code>: Opens a Google Sheets spreadsheet, or an Excel workbook stored in Google Drive, from its link. It is selected automatically when «filename» is a <code>https://docs.google.com/spreadsheets/d/...</code> link (copy it from your browser's address bar while the sheet is open), so «backend» can be omitted.
*; Requirements: A Google account with access to the spreadsheet. The first time, Analytica opens your web browser so you can sign in to Google and select the spreadsheet in Google's file chooser; the connection is remembered on your computer under your Windows account, never in the model, and you can revoke it from your Google account settings. Analytica can open only the spreadsheets you select in that chooser (plus ones it creates itself), so a link to a spreadsheet the chooser did not show cannot be opened. Pass an empty «filename» (or «showDialog»: True) to browse for a spreadsheet.
*; Capabilities: Reads come from a snapshot taken when the workbook is opened. Writes made with [[SpreadsheetSetCell]] and [[SpreadsheetSetRange]], and sheets added or removed, are sent to Google when the computation finishes, when you call [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]](wb), or when the workbook is refreshed: <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code> sends the pending writes and re-downloads the spreadsheet, so the values Google computed (and other people's edits) are seen. A native Google Sheet is exported by Google as an .xlsx snapshot (Google limits the export to 10 MB); an Excel workbook stored in Drive is downloaded as-is and written back as a whole file. The tab names the model sees (<code>SpreadsheetInfo(wb, 'Sheets')</code>, and «sheet» given by name) are the names in the exported snapshot, truncated to 31 characters, while writes are addressed to Google's real tab titles. <code>SpreadsheetOpen("New", backend:'GoogleSheets', title: "My sheet")</code> creates a new Google Sheet in your Drive. The second return value is the spreadsheet's link.
*; Return type: Returns a «GoogleSheetsWorkbook» object for a native Google Sheet, or a «LibXlWorkbook» object for an Excel file stored in Drive. <code>SpreadsheetInfo(wb, 'Backend')</code> returns <code>'GoogleSheets'</code> or <code>'LibXl'</code> accordingly, and <code>SpreadsheetInfo(wb, 'URL')</code> and <code>SpreadsheetInfo(wb, 'Account')</code> give its link and the Google account it was opened with.
*; Advanced: Analytica identifies itself to Google as an application registered by Lumina. An organization that would rather it identified itself as an application of their own -- because their Google Workspace administrator controls which outside applications may reach their data, for example -- can arrange that; see [[Using your own Google OAuth client]], which also covers asking Google for access to every spreadsheet so that the chooser is never shown.
*; Unattended use: A server, a scheduled job or [[Analytica Decision Engine|ADE]] on a machine where nobody is present cannot answer a browser. Give «account» a Google service account instead, and share the spreadsheet with its e-mail address -- see [[Using a Google service account]].
}}
}}
=== Example ===

:<code>SpreadsheetOpen("C:\MyModels\Sales Numbers.xlsx") → ''«ExcelWorkbook»''</code>

<div id="SpreadsheetCell"></div>

=== Getting the file name actually opened ===
Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. [[SpreadsheetOpen]] returns the file path as a second return value, which you can optionally capture using, e.g.,

:<code>[[Local]] (contents, filepath) := [[SpreadsheetOpen]]( ... );</code>

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using [[ComputedBy]] with the default filename as follows:

:Variable TheFilename ::=
::<code>[[ComputedBy]]( TheFileContetns, "defaultFilename.xlsx" ) </code>

:Variable TheWorkbook::=
::<code>( , TheFilename ) := [[SpreadsheetOpen]]( TheFilename )</code>

The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheWorkbook</code> is locally equivalent to:

:<code>[[Local]] (wb, filename ) := [[SpreadsheetOpen]]( TheFilename );</code>
:<code>TheFilename := filename;</code>
:<code>wb</code>

=== Use with Office 2010 ===

If you have installed the "Click-to-Run" version of Office 2010 from a web download, these spreadsheet functions may not work, due to a "feature" introduced in Office 2010 that apparently disables several common operations. In this case, you may need to re-install Office using the MSI-based edition. See how to do this at:

[http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx]

=== Excel 64-bit requires Analytica 64-bit ===

Analytica 32-bit cannot launch Excel 64-bit. (The other way around works). Thus, if you have installed Excel 64-bit (which we recommend), make sure you have installed Analytica 64-bit. If you are a [[Free Edition]] user, you probably have 32-bit installed, but you can install Analytica 64-bit from the [https://www.lumina.com/support/downloads/ Analytica Downloads page].

=== Remembering the selected filename ===

When [[SpreadsheetOpen]]() shows the file dialog and you select a file, it does not save the file name. So, the next time you load the model, you'll have to select the file again. If you want the model to remember the selected file, so it will just load it without asking, prompt using that file name as the default, you can use the '''SpreadsheetOpenEx''' function in the [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]].

=== Having same spreadsheet open in Excel at the same time ===

It is often useful to have the spreadsheet you are working with open in Excel at the same time your model is working with it. When you want to do this, is it best to open it Excel first, before evaluating [[SpreadsheetOpen]], in which case [[SpreadsheetOpen]] connects to the existing Excel process and to the currently open spreadsheet. If you change cells in Excel, then evaluate a spreadsheet read functions, you'll read the new values, and if your model writes to the spreadsheet, you'll see those values reflected immediately in the Excel interface.

When you call [[SpreadsheetOpen]] before opening the model in Excel, the situation is more complex. To understand what happens and how to view the same model in the Excel UI at the same time, see [[Simultaneously opening a spreadsheet in Excel and Analytica]].

=== SpreadsheetOpenFlags ===
A registry setting named <code>SpreadsheetOpenFlags</code> can be set to alter how [[SpreadsheetOpen]] connects to Excel and the initial settings in Excel. There is usually no reason to fiddle with these flags unless you encounter a specific problem. It has been more common to set these flags in server-based applications using ADE than from desktop Analytica.

You'll need to modify the sitting from RegEdit. You can set it in either
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
or
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
For ADE, set it in one of these hives:
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>

Setting it in HKLM causes it to apply from any account on your computer, while setting it from HKCU causes it to apply only to your own account. A setting in HKCU takes precedence over the same setting in HKLM.

Initially the value <code>SpreadsheetOpenFlags</code> will not be present. Create a new 32-bit DWORD with this name. The set the numeric value to an addition of any of these flags that you want:
* 1 = Launch using a COMCreateObject mechanism. (unset)=Launch using a BindToObject method.
*: A BindToObject method (the default for Desktop Analytica) makes it possible to connect to a Workbook running in an active Excel UI. A COMCreateObject mechanism launches a separate instance of Excel every time.
* 2 = Turn off Excel's Interactive flag.
* 4 = Turn off Excel's "Ask to update OLE links" flag.
* 8 = Turn off Excel's "Display Alerts"
* 16 = Disable Excel macros (for security)
* 32 = Close when visible.
*:Normally, if the workbook is currently visible in an Excel UI, Analytica simply disconnects from it, but doesn't force the workbook to close. The Excel UI is then responsible for eventually closing it. This overrides this and forces the workbook to close when the model releases it, even if it is visible.

=== From ADE ===
When using from ADE on a Web Server, we strongly advise against using Excel 2016 on the server. Excel 2010 works fairly well, but Excel 2016 is extremely unstable and has a tendency to fail unpredictably and lock up all other Excel instances. Microsoft responds by saying that Excel 2016 is not supported nor licensed for use on a web server.

When [[SpreadsheetOpen]] is evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the open completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

=== Debugging Errors ===
This section documents failures when '''SpreadsheetOpen''' has been unable to open Excel, and solutions.
* '''''Library not registered''''':
*:If this error occurs when '''SpreadsheetOpen''' is evaluated...
** The article [https://excel.tips.net/T002952_Library_Not_Registered_Error.html Library not registered error] explains how to solve this problem when it is caused by an Excel plug-in. It may be caused by a bad Excel add-in library. You should also run <code>excel.exe /regserver</code>.
** In one case, an Analytica user concluded that an older version of Excel was interfering with his newer 32-bit version of Excel. He uninstalled both and re-installed Excel 64-bit and the problem corrected itself. But, for a different user with this problem, these steps did not correct the problem.
** A common cause of this problem is when stray registry settings from Excel versions that had been installed and uninstalled interfere with your current version of Excel. This is most common after you roll back to an earlier release after uninstalling a later release. To test for this cause, start Power Shell and run:
**::<code>get-childitem -Path "HKLM:\Software\Classes\TypeLib\{00020813-0000-0000-C000-000000000046}"</code>
::If you see more than one version listed, with the most recent version number missing its mapping to Excel, then this is probably the cause. To fix, use <code>RegEdit</code> to delete the hive for the later version number.

== SpreadsheetCell(workbook, sheet, column, row'', what'') ==
</div>

Returns the value (or other information) of a cell of a worksheet given its coordinates. The function fully array abstracts, so you can get a range of cells by specifying the column and/or row as an array.

Parameters:
;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
;«sheet»: The name or number of a worksheet from the workbook. Number 1 is the first worksheet, etc.
:: If you specify <code>sheet: "*"</code>, it returns the cell value from ''column, row'' for all sheets in the workbook, indexed by <code>.Sheet</code>, a local index containing the names of the worksheets. This is a way to get a list of all the worksheets in the workbook. If you specify column and/or rows as arrays, you can also use this to get a 3D array for a range over all worksheets.
;«column»: The column label, e.g., <code>"A", "B"</code>, or <code>"AB"</code>, or the column number as an integer.
;«row»: The row number as an integer
;«what»: optional. Let's you get the formula or format information from the cell. See below under [[SpreadsheetRange]] for details.

If the worksheet cell is empty, it returns [[Null]]. It flags an error if «workbook» is not a valid workbook, if it does not contain «sheet», or if the coordinates are invalid.

=== Examples ===
These expressions are different ways to get the same result, the value from cell ''C7'' in the first sheet, <code>"Sheet1"</code> of workbook:
:<code>SpreadsheetCell(workbook, "Sheet1", "C", 7)</code>
:<code>SpreadsheetCell(workbook, "Sheet1", 3, 7)</code>
:<code>SpreadsheetCell(workbook, 1, 3, 7)</code>

Suppose the spreadsheet contains a 2-D table in the region ''C4:J19''. The columns of this table correspond to the years 2008..2015. The rows correspond to different assets. It is easier to refer to the columns by number, so that the columns "C" thru "J" are columns 3 thru 10. To hold this 2-D table, we need two indexes in Analytica, <code>Time</code> and <code>Asset</code>.

:<code>Index Time := 2008..2015</code>
:<code>Index Asset := 1..16</code>
:<code>Variable Workbook := SpreadsheetOpen("C:\Asset Data.xls")</code>
:<code>Variable Data := SpreadsheetCell( workbook, "Sheet1", @Time+2, @Asset+3)</code>

<div id="SpreadsheetRange">
== SpreadsheetRange(workbook, range'', colIndex, rowIndex, howToIndex, sheet, what'') ==
</div>

Returns the values (or other information) for a range of cells from an Excel worksheet. The «range» can be can be a cell address such as <code>"C7"</code> or cell range <code>"C7:F12"</code>, or the name of a range defined in the spreadsheet. If you want to read or write several cells or ranges in a spreadsheet, it is often convenient to use Excel's name mechanism and refer to them by name in Analytica.

If the range has multiple columns, the result has local index <code>.Column</code> unless you specify «colindex» as a parameter. Similarly, if the range has multiple rows, the result has local index <code>.Row</code> unless you specify «rowindex» as a parameter. Flags in «howToIndex» let you control whether the first row (column) should be used as labels for local index <code>.Row</code> or <code>.Column</code>.

If you specify a sheet name with no cells, e.g. <code>"Inputs!"</code>, it returns a table that includes all cells from that sheet that contain anything.

By default, it returns the number or text values from the range (or <code>NULL</code> if the cell is empty). You can use the «what» parameter to obtain the cell formula, address, format, styles, precedent, and dependent cells for each cell.

=== SpreadsheetRange Parameters ===

SpreadsheetRange has two required parameters:

;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
; «range»: A cell range. It may be a single cell address, e.g. <code>"B10"</code>, a range, e.g. <code>"A1:BC99"</code>, optionally with sheet name, e.g. <code>"Sheet1!A1:BC99"</code>, or a named range, e.g. <code>"Discount_rate"</code> defined in the spreadsheet. If the «range» doesn't mention the sheet name, you must specify «sheet» as a separate parameter.
:: If you specify the range as <code>"Sheet1!"</code>, with nothing after the "!", or omit «range» and specify only «sheet», it returns the smallest rectangular range that includes all used cells within the sheet.

SpreadsheetRange has four optional parameters relating to the indexes for a range with multiple columns or rows, or over multiple sheets:
;«colIndex»: (optional) An index to use for the column dimension of the result.
;«rowIndex»: (optional) An index to use for the row dimension of the result.
;«howToIndex»: (optional) Flags controlling how to index the result when «colIndex» or «rowIndex» are not specified. You can add any of these values to combine their effects:
::<code>1</code>: Force a column index even if the range spans only a single column. Has no effect if you specify «colIndex».
::<code> 2</code>: Force a row index even if the range spans only a single row. Has no effect if you specify «rowIndex».
::<code>4</code>: Use the first row of «range» as column labels in the local index <code>.Column</code>. Exclude this first row in the result returned.
::<code>8</code>: Use the first column of «range» as labels in the local index <code>.Row</code>. Exclude this first column in the result returned..
::<code>16</code>: Suppress the error message that is otherwise given if the sizes of «colIndex» or «rowIndex» do not match the size of the range.
;«sheet»: (optional) The name or number of a worksheet inside the workbook. It can be a list of sheets, in which case, the function will return a 3D table, indexed by this list as the third dimension.
;«what»: (optional) See below for details on this parameter.

=== Indexes of a cell range ===

The result may be a scalar (single cell), a column vector, a row vector, or a 2-D array, depending on the dimensions of the cell range. If the range has more than one row (or column), it will use a local index .Row (.Column) by default. By default, the elements of the .Row index contain the range's row numbers and elements of the column index contain its column labels. For example, if the range is <code>"C7:E12"</code>, <code>.Row</code> would contain the elements <code>[7, 8, 9, 10, 11, 12]</code> and <code>.Column</code> would contain <code>['C', 'D', 'E']</code>.

Or, you can use the first column (row) of the range as the values for the local index .Row (.Column), by specifying <code>howToIndex: 8</code> (<code>howToIndex: 4</code>, or <code>howToIndex: 12</code> for both .Row and .Column.) If you use, the first row (column) of the range as values of the local indexe(es), they will not be included in the value of the array returned. So, in that case, the range must have at least two rows (columns).

Alternatively, if you already have index(es), you can supply them to the «rowIndex» («colIndex») parameters. If you specify a «rowIndex» or «colIndex», that is shorter than the number of rows (columns) in the range, it truncates the result. If an index is too long, it pads the result with [[Null]]. In these cases, it gives a warning message unless you set flag <code>''howToIndex: 16''</code>.

If the range has just one column, the result normally will not have a local .Column index. But, you can force it to use a .Column with one element by setting <code>howToIndex: 1</code>. If you are using a named range and don't know how many columns it has, you might use this option to prevent an error occurring if you use [[Dot_operator::A.I|result.Column]] in an expression. Similarly, you can force it to use local <code>.Row</code> index even when the result has only a single row by specifying <code>howToIndex: 2</code>.

You can obtain the entire range of a worksheet with all cells that contain anything named <code>"Sheet1"</code> by specifying the «range» as <code>"Sheet1!"</code> or by omitting the «range» parameter and specifying just the «sheet» parameter.

=== Examples ===

The following examples use this spreadsheet:

:[[Image:WorksheetRange ExcelShot.jpg]]

This spreadsheet contains these named ranges:
:{| class="wikitable"
! Label !! Range
|-
| Rate || B1
|-
| Year || B3:F3
|-
| Cash_flow || B4:F4
|-
| Divisions || A7:A9
|-
| Employee_count || B7:F9
|}

:<code>SpreadsheetRange(wb, "Rate") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B1") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B3:F3") →</code>
:{| class="wikitable"
! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
| || 2008 || 2009 || 2010 || 2011 || 2012
|}

:<code>Index Year := CopyIndex( SpreadsheetRange(wb, "Year", howToIndex: 1));</code>
:<code>SpreadsheetRange(wb, "Cash_flow", colIndex: Year) →</code>
:{| class="wikitable"
! .Year → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
| || -100 || 10 || 30 || 50 || 60
|}

''Note'': <code>howToIndex: 1</code> was specified for <code>Year</code> here so that we would have a 1-D array even if only one year were present in the spreadsheet.

:<code>SpreadsheetRange(wb, "Employee_count") →</code>
:{| class="wikitable"
! !! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
! rowspan="3" | .Row<br>↓ !! 7
| 24 || 27 || 28 || 32 || 35
|-
! 8
| 13 || 13 || 13 || 13 || 13
|-
! 9
| 25 || 22 || 21 || 19 || 16
|}

:<code>Index Time := [2008, 2009, 2010, 2011, 2012];</code>
:<code>SpreadsheetRange(wb, "A7:F9", colIndex: Time, howToIndex: 8, sheet: 1) →</code>
:{| class="wikitable"
! !! Time → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
! rowspan="3" | .Row<br>↓ !! "Div A"
| 24 || 27 || 28 || 32 || 35
|-
! "Div B"
| 13 || 13 || 13 || 13 || 13
|-
! "Div C"
| 25 || 22 || 21 || 19 || 16
|}

To obtain the list of worksheet names:
:<code>SpreadsheetCell(wb, "*", 1, 1).Sheet</code>

To obtain all used cells in sheet named "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2")</code>

To obtain the number format of all cells in "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2", what:"NumberFormat")</code>

=== SpreadsheetRange «what» parameter ===

By default, SpreadsheetRange() returns the value of the cell(s) in the range, but you can use the «what» parameter to obtain the formula, cell style and formats, cell address, predecessor or dependent cells of each cell:
;«what»: (optional). By default, SpreadsheetRange returns the value of the range, but you can use this parameter to obtain its formula, or cell style parameters. Possible values:
::<code>"Value"</code>: (Default) The computed value. Excel dates become Analytica date-time numbers, which display as dates.
::<code>"NumericValue"</code>: The computed value, but dates are returned as numbers.
::<code>"Formula"</code>: The cell formula as a text value in the normal Excel format starting with "=", e.g., <code>"=Sum(D4:D10)"</code>
::<code>"RelativeFormula"</code>: The cell formula using relative offset format, e.g., <code>"=Sum(RC[-9]:R[+6]C[-9])"</code>

==== «what» parameter cell formats ====
::<code>"NumberFormat"</code>: The cell number format as text.
::<code>"BackColor"</code>: Cell background color as integer: ''red*65536 + green*256 + blue''
::<code>"Text Color"</code>: Font color as an integer: ''red*65536 + green*256 + blue''
::<code>"FontName"</code>: Name of the font used to display the cell
::<code>"FontSize"</code>: Point size of the font displayed in the cell
::<code>"FontStyle"</code>: Special font styles for cell separated by spaces, may include "bold italic underline strikethrough subscript superscript outline shadow"
::<code>"HorizontalAlignment"</code>: Text justification, one of: <code>'Left', 'Center', 'Right', 'Justify', 'Distributed', 'Fill'</code>. (''new to [[Analytica 5.0]]'')
::<code>"VerticalAlignment"</code>: Text vertical justification, one of: <code>'Top', 'Middle', 'Bottom', 'Justify', 'Distributed'</code>. (''new to [[Analytica 5.0]]'')
::<code>"WrapText"</code>: <code>0</code> or <code>1</code> controls whether text is word wrapped to fit in the cell.
::<code>"Border(Left|Right|Up|Down)"</code> show a border to left, right, above, or below the cell.
::<code>"Border(Left|Right|Up|Down)Color"</code>: Return the color of the specified side of the border as an RGB number -- E.g., <code>"BorderLeftColor"</code> returns an integer equal to ''red*65535+green*256+blue''
::<code>"Border (Left|Right|Up|Down) Style"</code>: Style of indicated border, or [[Null]] if not set. May be <code>"Solid", "Dash", "DashDot", "DashDotDot", "Dot", "Double"</code>, or <code>"SlantDashDot"</code>.
::<code>"Border (Left|Right|Up|Down) Weight"</code>: Thickness of indicated border, usually between 1 and 4

==== «what» parameter cell addresses ====
::<code>"Address"</code>: The address of the cell range, e.g., <code>"B12:C13"</code>
::<code>"AddressR1C1"</code>: The address of the cell range in R1C1 format, e.g., <code>"R12C2:R13C3"</code>
::<code>"Sheet"</code>: The sheet name where the cell range exists.
::<code>"RangeName"</code>: The name of the range, if it is a named range.

==== «what» parameter cell precedents and dependents ====

::<code>"DirectPrecedents"</code>: Addresses of all cells mentioned in the cell formula, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not precedents in other sheets.
::<code>"DirectPrecedentsRelative"</code>: Same as "DirectPrecedents", but cells are given by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"DirectDependents"</code>: Addresses of all cells whose formula mentions this cell, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not dependents in other sheets.
::<code>"DirectDependentsRelative"</code>: Same as <code>"DirectDependents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Precedents"</code>: Addresses of all cells in the current worksheet mentioned in the formula of this cell and the formulas of its direct precedents. It does not include cells reached by paths passing through other sheets.
::<code>"PrecedentsRelative"</code>: Same as <code>"Precedents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Descendants"</code>: Description of all cells in the current worksheet that depend directly or indirectly on the given cell. It does not include cells reached by paths passing through other sheets.
::<code>"DirectDescendantsRelative"</code>: Same as <code>"DirectDescendants"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.

=== Errors in SpreadsheetRange parameters ===
In a call to SpreadsheetRange(wb, range):
* If range refers to a sheet, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the worksheet 'sheet' was not found."
* If range refers to a named range, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the indicated named cell range, 'x', was not found."
* If range refers to a cell address with bad syntax, e.g. "ted!A1:R3C6", it gives an error message saying "the range named A1:R3C6 was not found in Excel worksheet 'ted'."

<div id="SpreadsheetInfo">
== SpreadsheetInfo(workbook, item) ==
</div>

SpreadsheetInfo gets various kinds of information about the spreadsheet («workbook») specified by parameter «item»:

{| class="wikitable"
! item !! Description
|-
| <code>"AcceptLabelsInFormulas"</code> || True when you can use labels in worksheet formulas. This is usually false.
|-
| <code>"Account"</code> || ''([[Analytica 7.2|7.2]])'' The Google account a workbook opened from Google Sheets or Google Drive is connected with. Null for other workbooks.
|-
| <code>"ActiveSheet"</code> || The number of the active (displayed) worksheet.
|-
| <code>"Author"</code> || The name of the author, usually the name of the person who created the spreadsheet as recorded by Windows OS.
|-
| <code>"Backend"</code> || ''([[Analytica 7.2|7.2]])'' Which engine holds the workbook: <code>'Excel'</code>, <code>'LibXl'</code> or <code>'GoogleSheets'</code> (see the «backend» parameter of [[SpreadsheetOpen]]).
|-
| <code>"CalculationMode"</code> || The calculation mode set for the workbook, which may be "Automatic", "Manual" or "Semiautomatic", meaning automatic except for data tables.
|-
| <code>"CalculationState"</code> || ''([[Analytica 5.0|5.0]])'' The current state of Excel's calculation engine, either <code>"Calculating"</code>, <code>"Pending"</code> or <code>"Done"</code>.
|-
| <code>"CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of the Excel calculation engine that the current workbook was last calculated in. If it was saved in an earlier version of Excel and hasn't yet been fully calculated, the value is 0. You can compare this to the "Excel.CalculationVersion" to determine whether it was last re-calculated using the same calculation engine as your current installed Excel.
|-
| <code>"CodeName"</code> ||
|-
| <code>"Date1904"</code> || The base for dates used in the workbook.
|-
| <code>"DecimalSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character used to separate a whole number from its fractional part. In English-speaking countries this is '.' (a dot).
|-
| <code>"Excel.CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of calculation engine for your installed version of Excel.
|-
| <code>"Filename"</code> || The name of the file, including the full file path.
|-
| <code>"Name"</code> || The name of the file, without the file path.
|-
| <code>"Names"</code> || A list of all the named ranges.
|-
| <code>"OperatingSystem"</code> || ''([[Analytica 5.0|5.0]])'' The name of the operating system that your Excel instance is running on, as reported by Excel.
|-
| <code>"ReadOnly"</code> || True (1) if the file is saved as Readonly.
|-
| <code>"Saved"</code> || False (0) if it has unsaved changes.
|-
| <code>"SelectedRange"</code> || The currently selected Range.
|-
| <code>"SelectedRangeR1C1"</code> || The currently selected Range specified by row and column number.
|-
| <code>"Sheets"</code> || A list of the names of all the worksheets
|-
| <code>"ThousandsSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character Excel uses to group thousands when displaying a large number. In English-speaking countries this is ',' (a comma). For example, in the number <code>1,234,456.78</code>, groups of thousands are separated by commas.
|-
| <code>"Title"</code> || The title of the spreadsheet
|-
| <code>"URL"</code> || ''([[Analytica 7.2|7.2]])'' The link of a workbook opened from Google Sheets or Google Drive. Null for other workbooks.
|-
| <code>"UseSystemSeparators"</code> || ''([[Analytica 5.0|5.0]])'' True when Excel uses <code>"DecimalSeparator"</code> and <code>"ThousandsSeparator"</code> for displaying numbers.
|-
| <code>"Version"</code> || ''([[Analytica 5.0|5.0]])'' The version number (text) for the installed release of Excel. Excel 2010 is "14.0", Excel 2013 is "15.0" and Excel 2016 is "16.0".
|-
| <code>"Visible"</code> || True when the Excel UI is visible.
|} The items above marked with ''([[Analytica 5.0|5.0]])'' require [[Analytica 5.0]] or better; those marked ''([[Analytica 7.2|7.2]])'' require [[Analytica 7.2]].

== History==

Functions for reading cells from Excel were first present in Analytica 4.1 with functions named [[OpenExcelFile]], [[WorksheetCell]] and [[WorksheetRange]], although these were labelled as ''experimental'', and the present functions were not officially available until 4.2.0. The old names are now deprecated, replaced with [[SpreadsheetOpen]], [[SpreadsheetCell]] and [[SpreadsheetRange]]. The old functions still work, but may be removed in future Analytica releases. The parameters have changed slightly from [[WorksheetRange]] to [[SpreadsheetRange]], with the sheet parameter moved from being the second to being the last parameter and now optional -- no longer required for named ranges or ranges of the form <code>"Sheet1!A1:Z99"</code>.

[[SpreadsheetInfo]] was introduced in [[Analytica 4.5]]. These options to [[SpreadsheetInfo]] were added in [[Analytica 5.0]]: "Version", "CalculationVersion", "Excel.CalculationVersion", "UseSystemSeparators", "DecimalSeparator", "ThousandsSeparator", and "CalculationState".

The color options for «what» incorrectly returned numbers in 0x00bbggrr order, instead of 0x00rrggbb order prior to [[Analytica 5.0]]. (This was a bug -- the documentation stated it should be 0x00rrggbb). Various options to the «what» parameter of [[SpreadsheetCell]] and [[SpreadsheetRange]] have appeared at different releases. The options <code>'HorizontalAlignment'</code> and <code>'VerticalAlignment'</code> appeared in [[Analytica 5.0]]. Options <code>'Address'</code>, <code>'AddressR1C1'</code>, <code>'Sheet'</code> and <code>'RangeName'</code> appeared in [[Analytica 4.6]]. The remaining options appeared in [[Analytica 4.4]], except for <code>'Value'</code>, <code>'NumericValue'</code>, <code>'Formula'</code>' and <code>'RelativeFormula'</code>, which appeared when the «what» parameter was introduced in [[Analytica 4.3]].

{{Release|1=7.2|2=|3=The <code>'GoogleSheets'</code> «backend» of [[SpreadsheetOpen]] (Google Sheets spreadsheets and Excel workbooks stored in Google Drive, opened from their link), and the "Backend", "URL" and "Account" items of [[SpreadsheetInfo]], were added in [[Analytica 7.2]].}}

== See Also ==

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[media:Spreadsheet Helper lib.ana|Spreadsheet Helper lib.ana]]
* [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]]
* [[Media:Functions for Reading Excel Worksheets.ana|Reading Excel Worksheets.ana]]
* [[Read and Write Spreadsheets]]
* [[Excel spreadsheets read and write]]
* [[Functions to Write Data to Excel Worksheets]] -- [[SpreadsheetSetCell]], [[SpreadsheetSetRange]] and [[SpreadsheetSave]]
* {{Release|1=7.2|2=|3=[[Using your own Google OAuth client]] -- connecting to Google Sheets through your own Google Cloud registration}}
* {{Release|1=7.2|2=|3=[[Using a Google service account]] -- opening a Google Sheet with no browser and nobody present}}
* You can also use [[DbQuery| ODBC]] -- a standard database access method to read from Excel spreadsheets.
* [[SuppressExcelAlerts]]
* [[Excel to Analytica Translation]]
* [[Excel to Analytica Mappings]]
* [[ReadTextFile]]
* [[ReadCsvFile]]
* You can use these functions from [[Excel Functions from ADE| ADE]].
* These spreadsheet functions above are more flexible than [[OLE linking]] which is also available.
* [[OLE linking]] </div>

Functions To Read Excel Worksheets

2026-09-18T15:46:10Z

Lchrisman: ER 21588 Phase 4: name the new account parameter in the SpreadsheetOpen heading

[[Category:Excel to Analytica mappings]]
[[Category:Integration Functions]]

__TOC__
{{ReleaseBar}}

These functions let you open an Excel spreadsheet file, and read cells and ranges from it. For writing to a spreadsheet, see [[Functions to Write Data to Excel Worksheets]].

<div id="SpreadsheetOpen" >
== SpreadsheetOpen(filename'', showDialog, title{{Release|7.0||, backend}}{{Release|7.2||, account}}'') ==
</div>

Opens a spreadsheet file and returns a workbook object for use by other functions (such as [[SpreadsheetCell]] or [[SpreadsheetRange]]) to read from or write to the file.

The returned object displays in a result table as <code>«ExcelWorkbook»</code>{{Release|7.2||, <code>«GoogleSheetsWorkbook»</code> }}{{Release|7.0|| or <code>«LibXlWorkbook»</code>, depending on the «backend» used.}} {{Release|1=7.2|2=|3=A workbook opened from a native Google Sheet displays as <code>«GoogleSheetsWorkbook»,</code> but an Excel file stored in Google Drive displays as <code>«LibXlWorkbook»</code>.}}

Unless you include a complete file path in «filename», Analytica looks for the file in the [[CurrentDataFolder]]. You can also provide the name of a workbook that is currently open in Excel, even if it has not yet been saved to disk.

If you omit the optional parameter «showDialog», the file browser dialog opens only if the specified file cannot be found.
* Set «showDialog» to True (<code>1</code>) to force the file browser even if the file exists.
* Set «showDialog» to False (<code>0</code>) to suppress the dialog entirely.

If no file is successfully opened, the function flags an error. You can customize the file dialog caption by passing text to the optional «title» parameter.

[[SpreadsheetOpen]] can return two values: the workbook object and the full path to the file that was opened. This is particularly useful when the user selects a file via the dialog:
::<code>Local (wb, filePath) := SpreadsheetOpen("Data.xlsx");</code>
{{Release|1=7.0|2=|3=
{{Release|1=7.1|2=|3=
=== Creating a new workbook ===
If you pass <code>"New"</code> as the «filename», SpreadsheetOpen creates a new blank workbook with a single empty sheet, without saving to any file. This is useful for building a workbook from scratch before saving it with [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]].

:<code>SpreadsheetOpen("New")</code> — Creates a new workbook using the Excel backend.
:<code>SpreadsheetOpen("New", backend:'LibXl')</code> — Creates a new workbook using the LibXl backend.

You can then add sheets using the <code>+</code> prefix in [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetRange|SpreadsheetSetRange]] or [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSetCell|SpreadsheetSetCell]], and save with SpreadsheetSave when done.
}}

=== Backend ===
''(New to [[Analytica 7.0]])''

The optional «backend» parameter determines which underlying engine Analytica uses to handle the spreadsheet.

* <code>'Excel'</code>: (Default) Uses the Microsoft Excel COM interface.
*;Requirements: Requires Microsoft Excel to be installed locally.
*;Capabilities: This backend includes the full Excel calculation engine. If you change cell values using [[SpreadsheetSetCell]] or [[SpreadsheetSetRange]], formulas within the workbook will be recalculated, allowing you to read back computed results. It supports all standard Excel file formats and features.
*;Return type: Returns an «ExcelWorkbook» object.

* <code>'LibXl'</code>: Uses a built-in library for direct file access.
*; Requirements: Does not require Microsoft Excel to be installed.
*; Capabilities: Offers high performance for reading and writing raw data. It is ideal for automated environments (like servers) where Excel might not be present. Note that it does '''''not''''' include a calculation engine; it reads literal values and formulas from the file but cannot "re-calc" a workbook after data is changed.
*; Return type: Returns a «LibXlWorkbook» object.
{{Release|1=7.2|2=|3=

* <code>'GoogleSheets'</code>: Opens a Google Sheets spreadsheet, or an Excel workbook stored in Google Drive, from its link. It is selected automatically when «filename» is a <code>https://docs.google.com/spreadsheets/d/...</code> link (copy it from your browser's address bar while the sheet is open), so «backend» can be omitted.
*; Requirements: A Google account with access to the spreadsheet. The first time, Analytica opens your web browser so you can sign in to Google and select the spreadsheet in Google's file chooser; the connection is remembered on your computer under your Windows account, never in the model, and you can revoke it from your Google account settings. Analytica can open only the spreadsheets you select in that chooser (plus ones it creates itself), so a link to a spreadsheet the chooser did not show cannot be opened. Pass an empty «filename» (or «showDialog»: True) to browse for a spreadsheet.
*; Capabilities: Reads come from a snapshot taken when the workbook is opened. Writes made with [[SpreadsheetSetCell]] and [[SpreadsheetSetRange]], and sheets added or removed, are sent to Google when the computation finishes, when you call [[Functions_to_Write_Data_to_Excel_Worksheets#SpreadsheetSave|SpreadsheetSave]](wb), or when the workbook is refreshed: <code>SpreadsheetSetInfo(wb, 'Refresh', true)</code> sends the pending writes and re-downloads the spreadsheet, so the values Google computed (and other people's edits) are seen. A native Google Sheet is exported by Google as an .xlsx snapshot (Google limits the export to 10 MB); an Excel workbook stored in Drive is downloaded as-is and written back as a whole file. The tab names the model sees (<code>SpreadsheetInfo(wb, 'Sheets')</code>, and «sheet» given by name) are the names in the exported snapshot, truncated to 31 characters, while writes are addressed to Google's real tab titles. <code>SpreadsheetOpen("New", backend:'GoogleSheets', title: "My sheet")</code> creates a new Google Sheet in your Drive. The second return value is the spreadsheet's link.
*; Return type: Returns a «GoogleSheetsWorkbook» object for a native Google Sheet, or a «LibXlWorkbook» object for an Excel file stored in Drive. <code>SpreadsheetInfo(wb, 'Backend')</code> returns <code>'GoogleSheets'</code> or <code>'LibXl'</code> accordingly, and <code>SpreadsheetInfo(wb, 'URL')</code> and <code>SpreadsheetInfo(wb, 'Account')</code> give its link and the Google account it was opened with.
*; Advanced: Analytica identifies itself to Google as an application registered by Lumina. An organization that would rather it identified itself as an application of their own -- because their Google Workspace administrator controls which outside applications may reach their data, for example -- can arrange that; see [[Using your own Google OAuth client]].
}}
}}
=== Example ===

:<code>SpreadsheetOpen("C:\MyModels\Sales Numbers.xlsx") → ''«ExcelWorkbook»''</code>

<div id="SpreadsheetCell"></div>

=== Getting the file name actually opened ===
Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. [[SpreadsheetOpen]] returns the file path as a second return value, which you can optionally capture using, e.g.,

:<code>[[Local]] (contents, filepath) := [[SpreadsheetOpen]]( ... );</code>

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using [[ComputedBy]] with the default filename as follows:

:Variable TheFilename ::=
::<code>[[ComputedBy]]( TheFileContetns, "defaultFilename.xlsx" ) </code>

:Variable TheWorkbook::=
::<code>( , TheFilename ) := [[SpreadsheetOpen]]( TheFilename )</code>

The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheWorkbook</code> is locally equivalent to:

:<code>[[Local]] (wb, filename ) := [[SpreadsheetOpen]]( TheFilename );</code>
:<code>TheFilename := filename;</code>
:<code>wb</code>

=== Use with Office 2010 ===

If you have installed the "Click-to-Run" version of Office 2010 from a web download, these spreadsheet functions may not work, due to a "feature" introduced in Office 2010 that apparently disables several common operations. In this case, you may need to re-install Office using the MSI-based edition. See how to do this at:

[http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx http://office.microsoft.com/en-gb/excel-help/click-to-run-switch-to-using-a-full-office-edition-HA101850538.aspx]

=== Excel 64-bit requires Analytica 64-bit ===

Analytica 32-bit cannot launch Excel 64-bit. (The other way around works). Thus, if you have installed Excel 64-bit (which we recommend), make sure you have installed Analytica 64-bit. If you are a [[Free Edition]] user, you probably have 32-bit installed, but you can install Analytica 64-bit from the [https://www.lumina.com/support/downloads/ Analytica Downloads page].

=== Remembering the selected filename ===

When [[SpreadsheetOpen]]() shows the file dialog and you select a file, it does not save the file name. So, the next time you load the model, you'll have to select the file again. If you want the model to remember the selected file, so it will just load it without asking, prompt using that file name as the default, you can use the '''SpreadsheetOpenEx''' function in the [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]].

=== Having same spreadsheet open in Excel at the same time ===

It is often useful to have the spreadsheet you are working with open in Excel at the same time your model is working with it. When you want to do this, is it best to open it Excel first, before evaluating [[SpreadsheetOpen]], in which case [[SpreadsheetOpen]] connects to the existing Excel process and to the currently open spreadsheet. If you change cells in Excel, then evaluate a spreadsheet read functions, you'll read the new values, and if your model writes to the spreadsheet, you'll see those values reflected immediately in the Excel interface.

When you call [[SpreadsheetOpen]] before opening the model in Excel, the situation is more complex. To understand what happens and how to view the same model in the Excel UI at the same time, see [[Simultaneously opening a spreadsheet in Excel and Analytica]].

=== SpreadsheetOpenFlags ===
A registry setting named <code>SpreadsheetOpenFlags</code> can be set to alter how [[SpreadsheetOpen]] connects to Excel and the initial settings in Excel. There is usually no reason to fiddle with these flags unless you encounter a specific problem. It has been more common to set these flags in server-based applications using ADE than from desktop Analytica.

You'll need to modify the sitting from RegEdit. You can set it in either
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
or
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
For ADE, set it in one of these hives:
:<code>HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>
:<code>HKEY_CURRENT_USER/Software/Lumina Decision Systems/Analytica/{{#svarget:anarelease|6.1}}</code>

Setting it in HKLM causes it to apply from any account on your computer, while setting it from HKCU causes it to apply only to your own account. A setting in HKCU takes precedence over the same setting in HKLM.

Initially the value <code>SpreadsheetOpenFlags</code> will not be present. Create a new 32-bit DWORD with this name. The set the numeric value to an addition of any of these flags that you want:
* 1 = Launch using a COMCreateObject mechanism. (unset)=Launch using a BindToObject method.
*: A BindToObject method (the default for Desktop Analytica) makes it possible to connect to a Workbook running in an active Excel UI. A COMCreateObject mechanism launches a separate instance of Excel every time.
* 2 = Turn off Excel's Interactive flag.
* 4 = Turn off Excel's "Ask to update OLE links" flag.
* 8 = Turn off Excel's "Display Alerts"
* 16 = Disable Excel macros (for security)
* 32 = Close when visible.
*:Normally, if the workbook is currently visible in an Excel UI, Analytica simply disconnects from it, but doesn't force the workbook to close. The Excel UI is then responsible for eventually closing it. This overrides this and forces the workbook to close when the model releases it, even if it is visible.

=== From ADE ===
When using from ADE on a Web Server, we strongly advise against using Excel 2016 on the server. Excel 2010 works fairly well, but Excel 2016 is extremely unstable and has a tendency to fail unpredictably and lock up all other Excel instances. Microsoft responds by saying that Excel 2016 is not supported nor licensed for use on a web server.

When [[SpreadsheetOpen]] is evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the open completes, it calls [[IAdeUICallbacks::FileOpenCompleted]]().

=== Debugging Errors ===
This section documents failures when '''SpreadsheetOpen''' has been unable to open Excel, and solutions.
* '''''Library not registered''''':
*:If this error occurs when '''SpreadsheetOpen''' is evaluated...
** The article [https://excel.tips.net/T002952_Library_Not_Registered_Error.html Library not registered error] explains how to solve this problem when it is caused by an Excel plug-in. It may be caused by a bad Excel add-in library. You should also run <code>excel.exe /regserver</code>.
** In one case, an Analytica user concluded that an older version of Excel was interfering with his newer 32-bit version of Excel. He uninstalled both and re-installed Excel 64-bit and the problem corrected itself. But, for a different user with this problem, these steps did not correct the problem.
** A common cause of this problem is when stray registry settings from Excel versions that had been installed and uninstalled interfere with your current version of Excel. This is most common after you roll back to an earlier release after uninstalling a later release. To test for this cause, start Power Shell and run:
**::<code>get-childitem -Path "HKLM:\Software\Classes\TypeLib\{00020813-0000-0000-C000-000000000046}"</code>
::If you see more than one version listed, with the most recent version number missing its mapping to Excel, then this is probably the cause. To fix, use <code>RegEdit</code> to delete the hive for the later version number.

== SpreadsheetCell(workbook, sheet, column, row'', what'') ==
</div>

Returns the value (or other information) of a cell of a worksheet given its coordinates. The function fully array abstracts, so you can get a range of cells by specifying the column and/or row as an array.

Parameters:
;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
;«sheet»: The name or number of a worksheet from the workbook. Number 1 is the first worksheet, etc.
:: If you specify <code>sheet: "*"</code>, it returns the cell value from ''column, row'' for all sheets in the workbook, indexed by <code>.Sheet</code>, a local index containing the names of the worksheets. This is a way to get a list of all the worksheets in the workbook. If you specify column and/or rows as arrays, you can also use this to get a 3D array for a range over all worksheets.
;«column»: The column label, e.g., <code>"A", "B"</code>, or <code>"AB"</code>, or the column number as an integer.
;«row»: The row number as an integer
;«what»: optional. Let's you get the formula or format information from the cell. See below under [[SpreadsheetRange]] for details.

If the worksheet cell is empty, it returns [[Null]]. It flags an error if «workbook» is not a valid workbook, if it does not contain «sheet», or if the coordinates are invalid.

=== Examples ===
These expressions are different ways to get the same result, the value from cell ''C7'' in the first sheet, <code>"Sheet1"</code> of workbook:
:<code>SpreadsheetCell(workbook, "Sheet1", "C", 7)</code>
:<code>SpreadsheetCell(workbook, "Sheet1", 3, 7)</code>
:<code>SpreadsheetCell(workbook, 1, 3, 7)</code>

Suppose the spreadsheet contains a 2-D table in the region ''C4:J19''. The columns of this table correspond to the years 2008..2015. The rows correspond to different assets. It is easier to refer to the columns by number, so that the columns "C" thru "J" are columns 3 thru 10. To hold this 2-D table, we need two indexes in Analytica, <code>Time</code> and <code>Asset</code>.

:<code>Index Time := 2008..2015</code>
:<code>Index Asset := 1..16</code>
:<code>Variable Workbook := SpreadsheetOpen("C:\Asset Data.xls")</code>
:<code>Variable Data := SpreadsheetCell( workbook, "Sheet1", @Time+2, @Asset+3)</code>

<div id="SpreadsheetRange">
== SpreadsheetRange(workbook, range'', colIndex, rowIndex, howToIndex, sheet, what'') ==
</div>

Returns the values (or other information) for a range of cells from an Excel worksheet. The «range» can be can be a cell address such as <code>"C7"</code> or cell range <code>"C7:F12"</code>, or the name of a range defined in the spreadsheet. If you want to read or write several cells or ranges in a spreadsheet, it is often convenient to use Excel's name mechanism and refer to them by name in Analytica.

If the range has multiple columns, the result has local index <code>.Column</code> unless you specify «colindex» as a parameter. Similarly, if the range has multiple rows, the result has local index <code>.Row</code> unless you specify «rowindex» as a parameter. Flags in «howToIndex» let you control whether the first row (column) should be used as labels for local index <code>.Row</code> or <code>.Column</code>.

If you specify a sheet name with no cells, e.g. <code>"Inputs!"</code>, it returns a table that includes all cells from that sheet that contain anything.

By default, it returns the number or text values from the range (or <code>NULL</code> if the cell is empty). You can use the «what» parameter to obtain the cell formula, address, format, styles, precedent, and dependent cells for each cell.

=== SpreadsheetRange Parameters ===

SpreadsheetRange has two required parameters:

;«workbook»: A workbook object returned by [[SpreadsheetOpen]]()
; «range»: A cell range. It may be a single cell address, e.g. <code>"B10"</code>, a range, e.g. <code>"A1:BC99"</code>, optionally with sheet name, e.g. <code>"Sheet1!A1:BC99"</code>, or a named range, e.g. <code>"Discount_rate"</code> defined in the spreadsheet. If the «range» doesn't mention the sheet name, you must specify «sheet» as a separate parameter.
:: If you specify the range as <code>"Sheet1!"</code>, with nothing after the "!", or omit «range» and specify only «sheet», it returns the smallest rectangular range that includes all used cells within the sheet.

SpreadsheetRange has four optional parameters relating to the indexes for a range with multiple columns or rows, or over multiple sheets:
;«colIndex»: (optional) An index to use for the column dimension of the result.
;«rowIndex»: (optional) An index to use for the row dimension of the result.
;«howToIndex»: (optional) Flags controlling how to index the result when «colIndex» or «rowIndex» are not specified. You can add any of these values to combine their effects:
::<code>1</code>: Force a column index even if the range spans only a single column. Has no effect if you specify «colIndex».
::<code> 2</code>: Force a row index even if the range spans only a single row. Has no effect if you specify «rowIndex».
::<code>4</code>: Use the first row of «range» as column labels in the local index <code>.Column</code>. Exclude this first row in the result returned.
::<code>8</code>: Use the first column of «range» as labels in the local index <code>.Row</code>. Exclude this first column in the result returned..
::<code>16</code>: Suppress the error message that is otherwise given if the sizes of «colIndex» or «rowIndex» do not match the size of the range.
;«sheet»: (optional) The name or number of a worksheet inside the workbook. It can be a list of sheets, in which case, the function will return a 3D table, indexed by this list as the third dimension.
;«what»: (optional) See below for details on this parameter.

=== Indexes of a cell range ===

The result may be a scalar (single cell), a column vector, a row vector, or a 2-D array, depending on the dimensions of the cell range. If the range has more than one row (or column), it will use a local index .Row (.Column) by default. By default, the elements of the .Row index contain the range's row numbers and elements of the column index contain its column labels. For example, if the range is <code>"C7:E12"</code>, <code>.Row</code> would contain the elements <code>[7, 8, 9, 10, 11, 12]</code> and <code>.Column</code> would contain <code>['C', 'D', 'E']</code>.

Or, you can use the first column (row) of the range as the values for the local index .Row (.Column), by specifying <code>howToIndex: 8</code> (<code>howToIndex: 4</code>, or <code>howToIndex: 12</code> for both .Row and .Column.) If you use, the first row (column) of the range as values of the local indexe(es), they will not be included in the value of the array returned. So, in that case, the range must have at least two rows (columns).

Alternatively, if you already have index(es), you can supply them to the «rowIndex» («colIndex») parameters. If you specify a «rowIndex» or «colIndex», that is shorter than the number of rows (columns) in the range, it truncates the result. If an index is too long, it pads the result with [[Null]]. In these cases, it gives a warning message unless you set flag <code>''howToIndex: 16''</code>.

If the range has just one column, the result normally will not have a local .Column index. But, you can force it to use a .Column with one element by setting <code>howToIndex: 1</code>. If you are using a named range and don't know how many columns it has, you might use this option to prevent an error occurring if you use [[Dot_operator::A.I|result.Column]] in an expression. Similarly, you can force it to use local <code>.Row</code> index even when the result has only a single row by specifying <code>howToIndex: 2</code>.

You can obtain the entire range of a worksheet with all cells that contain anything named <code>"Sheet1"</code> by specifying the «range» as <code>"Sheet1!"</code> or by omitting the «range» parameter and specifying just the «sheet» parameter.

=== Examples ===

The following examples use this spreadsheet:

:[[Image:WorksheetRange ExcelShot.jpg]]

This spreadsheet contains these named ranges:
:{| class="wikitable"
! Label !! Range
|-
| Rate || B1
|-
| Year || B3:F3
|-
| Cash_flow || B4:F4
|-
| Divisions || A7:A9
|-
| Employee_count || B7:F9
|}

:<code>SpreadsheetRange(wb, "Rate") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B1") → 0.08</code>
:<code>SpreadsheetRange(wb, "Sheet1!B3:F3") →</code>
:{| class="wikitable"
! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
| || 2008 || 2009 || 2010 || 2011 || 2012
|}

:<code>Index Year := CopyIndex( SpreadsheetRange(wb, "Year", howToIndex: 1));</code>
:<code>SpreadsheetRange(wb, "Cash_flow", colIndex: Year) →</code>
:{| class="wikitable"
! .Year → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
| || -100 || 10 || 30 || 50 || 60
|}

''Note'': <code>howToIndex: 1</code> was specified for <code>Year</code> here so that we would have a 1-D array even if only one year were present in the spreadsheet.

:<code>SpreadsheetRange(wb, "Employee_count") →</code>
:{| class="wikitable"
! !! .Column → !! 'B' !! 'C' !! 'D' !! 'E' !! 'F'
|-
! rowspan="3" | .Row<br>↓ !! 7
| 24 || 27 || 28 || 32 || 35
|-
! 8
| 13 || 13 || 13 || 13 || 13
|-
! 9
| 25 || 22 || 21 || 19 || 16
|}

:<code>Index Time := [2008, 2009, 2010, 2011, 2012];</code>
:<code>SpreadsheetRange(wb, "A7:F9", colIndex: Time, howToIndex: 8, sheet: 1) →</code>
:{| class="wikitable"
! !! Time → !! 2008 !! 2009 !! 2010 !! 2011 !! 2012
|-
! rowspan="3" | .Row<br>↓ !! "Div A"
| 24 || 27 || 28 || 32 || 35
|-
! "Div B"
| 13 || 13 || 13 || 13 || 13
|-
! "Div C"
| 25 || 22 || 21 || 19 || 16
|}

To obtain the list of worksheet names:
:<code>SpreadsheetCell(wb, "*", 1, 1).Sheet</code>

To obtain all used cells in sheet named "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2")</code>

To obtain the number format of all cells in "Sheet2":
:<code>SpreadsheetRange(wb, sheet:"Sheet2", what:"NumberFormat")</code>

=== SpreadsheetRange «what» parameter ===

By default, SpreadsheetRange() returns the value of the cell(s) in the range, but you can use the «what» parameter to obtain the formula, cell style and formats, cell address, predecessor or dependent cells of each cell:
;«what»: (optional). By default, SpreadsheetRange returns the value of the range, but you can use this parameter to obtain its formula, or cell style parameters. Possible values:
::<code>"Value"</code>: (Default) The computed value. Excel dates become Analytica date-time numbers, which display as dates.
::<code>"NumericValue"</code>: The computed value, but dates are returned as numbers.
::<code>"Formula"</code>: The cell formula as a text value in the normal Excel format starting with "=", e.g., <code>"=Sum(D4:D10)"</code>
::<code>"RelativeFormula"</code>: The cell formula using relative offset format, e.g., <code>"=Sum(RC[-9]:R[+6]C[-9])"</code>

==== «what» parameter cell formats ====
::<code>"NumberFormat"</code>: The cell number format as text.
::<code>"BackColor"</code>: Cell background color as integer: ''red*65536 + green*256 + blue''
::<code>"Text Color"</code>: Font color as an integer: ''red*65536 + green*256 + blue''
::<code>"FontName"</code>: Name of the font used to display the cell
::<code>"FontSize"</code>: Point size of the font displayed in the cell
::<code>"FontStyle"</code>: Special font styles for cell separated by spaces, may include "bold italic underline strikethrough subscript superscript outline shadow"
::<code>"HorizontalAlignment"</code>: Text justification, one of: <code>'Left', 'Center', 'Right', 'Justify', 'Distributed', 'Fill'</code>. (''new to [[Analytica 5.0]]'')
::<code>"VerticalAlignment"</code>: Text vertical justification, one of: <code>'Top', 'Middle', 'Bottom', 'Justify', 'Distributed'</code>. (''new to [[Analytica 5.0]]'')
::<code>"WrapText"</code>: <code>0</code> or <code>1</code> controls whether text is word wrapped to fit in the cell.
::<code>"Border(Left|Right|Up|Down)"</code> show a border to left, right, above, or below the cell.
::<code>"Border(Left|Right|Up|Down)Color"</code>: Return the color of the specified side of the border as an RGB number -- E.g., <code>"BorderLeftColor"</code> returns an integer equal to ''red*65535+green*256+blue''
::<code>"Border (Left|Right|Up|Down) Style"</code>: Style of indicated border, or [[Null]] if not set. May be <code>"Solid", "Dash", "DashDot", "DashDotDot", "Dot", "Double"</code>, or <code>"SlantDashDot"</code>.
::<code>"Border (Left|Right|Up|Down) Weight"</code>: Thickness of indicated border, usually between 1 and 4

==== «what» parameter cell addresses ====
::<code>"Address"</code>: The address of the cell range, e.g., <code>"B12:C13"</code>
::<code>"AddressR1C1"</code>: The address of the cell range in R1C1 format, e.g., <code>"R12C2:R13C3"</code>
::<code>"Sheet"</code>: The sheet name where the cell range exists.
::<code>"RangeName"</code>: The name of the range, if it is a named range.

==== «what» parameter cell precedents and dependents ====

::<code>"DirectPrecedents"</code>: Addresses of all cells mentioned in the cell formula, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not precedents in other sheets.
::<code>"DirectPrecedentsRelative"</code>: Same as "DirectPrecedents", but cells are given by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"DirectDependents"</code>: Addresses of all cells whose formula mentions this cell, separated by commas. Unfortunately, Excel lists only cells in the same sheet, but not dependents in other sheets.
::<code>"DirectDependentsRelative"</code>: Same as <code>"DirectDependents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Precedents"</code>: Addresses of all cells in the current worksheet mentioned in the formula of this cell and the formulas of its direct precedents. It does not include cells reached by paths passing through other sheets.
::<code>"PrecedentsRelative"</code>: Same as <code>"Precedents"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.
::<code>"Descendants"</code>: Description of all cells in the current worksheet that depend directly or indirectly on the given cell. It does not include cells reached by paths passing through other sheets.
::<code>"DirectDescendantsRelative"</code>: Same as <code>"DirectDescendants"</code>, but cells are identified by their offset relative to the current cell, e.g., <code>R[-3]C[6]</code>.

=== Errors in SpreadsheetRange parameters ===
In a call to SpreadsheetRange(wb, range):
* If range refers to a sheet, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the worksheet 'sheet' was not found."
* If range refers to a named range, e.g. "sheet!x" that does not exist in workbook wb, it gives an error message saying "the indicated named cell range, 'x', was not found."
* If range refers to a cell address with bad syntax, e.g. "ted!A1:R3C6", it gives an error message saying "the range named A1:R3C6 was not found in Excel worksheet 'ted'."

<div id="SpreadsheetInfo">
== SpreadsheetInfo(workbook, item) ==
</div>

SpreadsheetInfo gets various kinds of information about the spreadsheet («workbook») specified by parameter «item»:

{| class="wikitable"
! item !! Description
|-
| <code>"AcceptLabelsInFormulas"</code> || True when you can use labels in worksheet formulas. This is usually false.
|-
| <code>"Account"</code> || ''([[Analytica 7.2|7.2]])'' The Google account a workbook opened from Google Sheets or Google Drive is connected with. Null for other workbooks.
|-
| <code>"ActiveSheet"</code> || The number of the active (displayed) worksheet.
|-
| <code>"Author"</code> || The name of the author, usually the name of the person who created the spreadsheet as recorded by Windows OS.
|-
| <code>"Backend"</code> || ''([[Analytica 7.2|7.2]])'' Which engine holds the workbook: <code>'Excel'</code>, <code>'LibXl'</code> or <code>'GoogleSheets'</code> (see the «backend» parameter of [[SpreadsheetOpen]]).
|-
| <code>"CalculationMode"</code> || The calculation mode set for the workbook, which may be "Automatic", "Manual" or "Semiautomatic", meaning automatic except for data tables.
|-
| <code>"CalculationState"</code> || ''([[Analytica 5.0|5.0]])'' The current state of Excel's calculation engine, either <code>"Calculating"</code>, <code>"Pending"</code> or <code>"Done"</code>.
|-
| <code>"CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of the Excel calculation engine that the current workbook was last calculated in. If it was saved in an earlier version of Excel and hasn't yet been fully calculated, the value is 0. You can compare this to the "Excel.CalculationVersion" to determine whether it was last re-calculated using the same calculation engine as your current installed Excel.
|-
| <code>"CodeName"</code> ||
|-
| <code>"Date1904"</code> || The base for dates used in the workbook.
|-
| <code>"DecimalSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character used to separate a whole number from its fractional part. In English-speaking countries this is '.' (a dot).
|-
| <code>"Excel.CalculationVersion"</code> || ''([[Analytica 5.0|5.0]])'' Number equal to 10000 * major + minor, encoding the version of calculation engine for your installed version of Excel.
|-
| <code>"Filename"</code> || The name of the file, including the full file path.
|-
| <code>"Name"</code> || The name of the file, without the file path.
|-
| <code>"Names"</code> || A list of all the named ranges.
|-
| <code>"OperatingSystem"</code> || ''([[Analytica 5.0|5.0]])'' The name of the operating system that your Excel instance is running on, as reported by Excel.
|-
| <code>"ReadOnly"</code> || True (1) if the file is saved as Readonly.
|-
| <code>"Saved"</code> || False (0) if it has unsaved changes.
|-
| <code>"SelectedRange"</code> || The currently selected Range.
|-
| <code>"SelectedRangeR1C1"</code> || The currently selected Range specified by row and column number.
|-
| <code>"Sheets"</code> || A list of the names of all the worksheets
|-
| <code>"ThousandsSeparator"</code> || ''([[Analytica 5.0|5.0]])'' The character Excel uses to group thousands when displaying a large number. In English-speaking countries this is ',' (a comma). For example, in the number <code>1,234,456.78</code>, groups of thousands are separated by commas.
|-
| <code>"Title"</code> || The title of the spreadsheet
|-
| <code>"URL"</code> || ''([[Analytica 7.2|7.2]])'' The link of a workbook opened from Google Sheets or Google Drive. Null for other workbooks.
|-
| <code>"UseSystemSeparators"</code> || ''([[Analytica 5.0|5.0]])'' True when Excel uses <code>"DecimalSeparator"</code> and <code>"ThousandsSeparator"</code> for displaying numbers.
|-
| <code>"Version"</code> || ''([[Analytica 5.0|5.0]])'' The version number (text) for the installed release of Excel. Excel 2010 is "14.0", Excel 2013 is "15.0" and Excel 2016 is "16.0".
|-
| <code>"Visible"</code> || True when the Excel UI is visible.
|} The items above marked with ''([[Analytica 5.0|5.0]])'' require [[Analytica 5.0]] or better; those marked ''([[Analytica 7.2|7.2]])'' require [[Analytica 7.2]].

== History==

Functions for reading cells from Excel were first present in Analytica 4.1 with functions named [[OpenExcelFile]], [[WorksheetCell]] and [[WorksheetRange]], although these were labelled as ''experimental'', and the present functions were not officially available until 4.2.0. The old names are now deprecated, replaced with [[SpreadsheetOpen]], [[SpreadsheetCell]] and [[SpreadsheetRange]]. The old functions still work, but may be removed in future Analytica releases. The parameters have changed slightly from [[WorksheetRange]] to [[SpreadsheetRange]], with the sheet parameter moved from being the second to being the last parameter and now optional -- no longer required for named ranges or ranges of the form <code>"Sheet1!A1:Z99"</code>.

[[SpreadsheetInfo]] was introduced in [[Analytica 4.5]]. These options to [[SpreadsheetInfo]] were added in [[Analytica 5.0]]: "Version", "CalculationVersion", "Excel.CalculationVersion", "UseSystemSeparators", "DecimalSeparator", "ThousandsSeparator", and "CalculationState".

The color options for «what» incorrectly returned numbers in 0x00bbggrr order, instead of 0x00rrggbb order prior to [[Analytica 5.0]]. (This was a bug -- the documentation stated it should be 0x00rrggbb). Various options to the «what» parameter of [[SpreadsheetCell]] and [[SpreadsheetRange]] have appeared at different releases. The options <code>'HorizontalAlignment'</code> and <code>'VerticalAlignment'</code> appeared in [[Analytica 5.0]]. Options <code>'Address'</code>, <code>'AddressR1C1'</code>, <code>'Sheet'</code> and <code>'RangeName'</code> appeared in [[Analytica 4.6]]. The remaining options appeared in [[Analytica 4.4]], except for <code>'Value'</code>, <code>'NumericValue'</code>, <code>'Formula'</code>' and <code>'RelativeFormula'</code>, which appeared when the «what» parameter was introduced in [[Analytica 4.3]].

{{Release|1=7.2|2=|3=The <code>'GoogleSheets'</code> «backend» of [[SpreadsheetOpen]] (Google Sheets spreadsheets and Excel workbooks stored in Google Drive, opened from their link), and the "Backend", "URL" and "Account" items of [[SpreadsheetInfo]], were added in [[Analytica 7.2]].}}

== See Also ==

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* [[media:Spreadsheet Helper lib.ana|Spreadsheet Helper lib.ana]]
* [[Analytica_Libraries_and_Templates#Spreadsheet_Helper_Library|Spreadsheet Helper Library]]
* [[Media:Functions for Reading Excel Worksheets.ana|Reading Excel Worksheets.ana]]
* [[Read and Write Spreadsheets]]
* [[Excel spreadsheets read and write]]
* [[Functions to Write Data to Excel Worksheets]] -- [[SpreadsheetSetCell]], [[SpreadsheetSetRange]] and [[SpreadsheetSave]]
* {{Release|1=7.2|2=|3=[[Using your own Google OAuth client]] -- connecting to Google Sheets through your own Google Cloud registration}}
* You can also use [[DbQuery| ODBC]] -- a standard database access method to read from Excel spreadsheets.
* [[SuppressExcelAlerts]]
* [[Excel to Analytica Translation]]
* [[Excel to Analytica Mappings]]
* [[ReadTextFile]]
* [[ReadCsvFile]]
* You can use these functions from [[Excel Functions from ADE| ADE]].
* These spreadsheet functions above are more flexible than [[OLE linking]] which is also available.
* [[OLE linking]] </div>