Thursday, 26 November 2015

Using Scopes in Acumatica

Hi Everyone,

During developing on Acumatica, you may face some restriction, from the platform side, for example:
  • You can select data only according to current user rights - if user does not have access to branch, there is no way to get data related to another branch.
  • There is restriction to read data just from current tenant, now way to get consolidated data by several tenants.
  • You are not able to read deleted data.
  • You can read data just within one connection to database.
All these stuff and some more is configuration of the platform. To give you ability to control these behavior Acumatica has a set of internal classes "Scopes". When you initialize scope it will tweak framework, to allow you do some forbidden stuff by default. When you dispose scope, it will revert all settings to the previous state.
Scope changes are applicable only for the current thread and will not affect other users/threads.
Also scope, if you use scope like here:

using (new SomeScope())
{
//Do some logic here
}

It will affects only the underlined code. System automatically revert changes when code leaves this block.

Now, lets discuss what types of scopes you can use in Acumatica:
  • PXInvariantCultureScope - Changes current Thread and UI culture to  invariant. All underlined code will use system invariant cuulture for localization, translating  comparing and converting values to string.
  • LocaleScope - Changes current locale to the specified in session (PXContext.Session["LocaleName"]). All underlined code will use translations, converting and comparing roles that are associated with provided on Acumatica Locales screen.
  • PXScreenIDScope - changes current Screen Id in Acumatica context. It affects AccessInfo.ScreenID during PX Graph initialization.
  • PXPreserveScope - during each request from browser to server, system will initialize graph, that is associated with current screen. During initialization, graph will instantiate all caches that are associated with declared data views. In the same time cache during initialization will read saved collections from session (inserted/updated/deleted/held records, current record). During disposing system will put all these collections back to server. Each graph and cache has own collections in sessions, so system can store saved information for many graphs and caches simultaneously. When you construct graph by your own form code, system will not load data from session, as you may want to do redirect or other processing. But using PXPreserveScope you can override this behavior.
  • PXLoginScope - using this scope you can change user and company (tenant), that will be used for running underlined code. These changes will affects access rights and selected data. Using this scope, you can read data from different tenant. But there is some restriction for modifying and insertion of data, so this is not recommended way.
  • PXIdentityScope - This is specific scope for specific server configuration. If you use windows authentication to SQL server and you are trying to create a new thread manually, you may need this scope to impersonate current thread user from user that is defined for w3wp process, to user that is defined for site.
  • PXImpersonationScope - is combination between PXLoginScope and PXIdentityScope. This scope will change both, thread windows user and acumatica login.
  • PXReadDeletedScope - special scope that will infor system that you want to read all data from the database, including data, that is marked as deleted with DeletedDatabaseRecord. Also you can read just deleted data without reading existing ones.
  • PXConnectionScope - this scope will initialize new connection to the database for all underlined code. All selects will use new connection, so you can read data from the database even if you already have open data-reader.
  • PXTransactionScope - this scope will initialize new transaction, so you can wrap-up some changes into transaction, when system will revert all changes together on any exception. Do not forget to call commit for the transaction scope before dispose it.
  • PXCommandScope - using this cope you can add some control to the command that will be generated to SQL server. For example, you may increase default timeout, or add other additional configuration.
  • PXReadBranchRestrictedScope - with this scope you can remove restriction by branches that will be automatically applied by the system core, if you have BranchID attribute in the selected DAC. 
  • PXTimeStampScope - if you have PXTStampAttribute on your data access class, system will always validate version of the record before saving it. But you can adjust version using this scope.
  • PXDBQueryHintsScope - When system runs statements against the sql, core can add some optimizations to do performance of query better. You can control this feature using QueryHintsScope. Right now you can use these hints: SqlServerOptionRecompile, SqlServerOptimizeForUnknown, MySqlLowPriority, MySqlHighPriority, MySqlLockInShareMode, MySqlNoCache.
  • PXConnectionStringScope - this scope can be used to change connection string to sql server on the fly. Be careful with this scope, as it may be dangerous to change database on the fly.
  • ReadOnlyScope - This scope will automatically restore IsDirty flags for provided caches, after changes in the underlined code.

No comments: